25:["$","title",null,{"children":"Introduction to D3 | Visualização | Observable"}] 49:T4a7,Grammars like [Vega-Lite](https://observablehq.com/@stanfordvis/introduction-to-vega-lite) 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 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. We also get far more control over the interaction capabilities of the visualizations.4a:T475,We created this list usng D3 (you can expand the cell above to see the code). We will explain how this code works later. But for now assume that the list was made by having D3 create the ordered list (`

`). 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). The [`d3.select`](https://github.com/d3/d3-selection#select) and [`d3.selectAll`](https://github.com/d3/d3-selection#selectAll) functions 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. First, 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:4b:T5f5,
## SVG: Scalable Vector Graphics 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. 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 setting their _y_ positions. This approach would break our _visual encoding_ abstraction of mapping data values to visual properties, and would yield a more difficult and brittle design process. 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:4c:T577,
## Summary 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).4d:[{"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":1680014044992.855,"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":1680014044992.855,"size":25363}] 29:{"id":"8e855b74bc52ee3e","slug":null,"title":"Introduction to D3","thumbnail":"49e3b8e7b5c25c76853ac31b4ed41e895e2facb91573182f4e68e995d0ccb899","access_level":"public","create_time":"$D2023-03-28T14:34:04.992Z","update_time":"$D2023-04-04T15:25:25.908Z","view_time":null,"first_public_time":"$D2023-03-28T14:34:04.992Z","has_unpublished_edits":null,"fork":true,"stars":0,"starred":false,"owner":{"type":"team","id":"ba46d53cd92022c6","login":"datavisbarrafas","name":"Visualização","avatar_url":"https://avatars-next.observableusercontent.com/91f6fa5dc6b1dbedd8f176d7af8c62b8883701f35fa480fe14c3fea0e52b8954","tier":"starter_2024","bio":"","following":false},"version":374,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"03096d7517f4f329","login":"barrafas","name":"Tiago Barradas","avatar_url":"https://avatars-next.observableusercontent.com/e73be1a419e1adb4b0d05a0aeb1c2e537bfe4de32cb4fb75c44f237c757d4c1c","tier":null,"bio":"","following":false}],"members":[{"type":"individual","id":"03096d7517f4f329","login":"barrafas","name":"Tiago Barradas","avatar_url":"https://avatars-next.observableusercontent.com/e73be1a419e1adb4b0d05a0aeb1c2e537bfe4de32cb4fb75c44f237c757d4c1c","tier":null,"role":"editor"},{"type":"team","id":"ba46d53cd92022c6","login":"datavisbarrafas","name":"Visualização","avatar_url":"https://avatars-next.observableusercontent.com/91f6fa5dc6b1dbedd8f176d7af8c62b8883701f35fa480fe14c3fea0e52b8954","tier":"starter_2024","role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"titling":"auto","title":"Introduction to D3","cells":[{"id":0,"value":"# Introduction to D3","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":3,"value":"$49","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":6,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":8,"value":"_This document is based on an original notebook by the [MIT Visualization Group](https://observablehq.com/@mitvis/introduction-to-d3) which was later updated by the [UW Interactive Data Lab](https://observablehq.com/@uwdata/introduction-to-d3-part-1)._","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":10,"value":"d3 = require('d3@7')","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":16,"value":"Next let's load a dataset to work with. We'll use a dataset on global health and population measures from 1955–2000, 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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":18,"value":"gapminder = datasets['gapminder.json']()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":49,"value":"printTable(gapminder.slice(0, 10))","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":50,"value":"_Note that we have put a [**Imports**](https://observablehq.com/@stanfordvis/introduction-to-d3#imports) section at the end of this document where we import various utility functions such as the `printTable()` function._","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":58,"value":"Let's also extract a subset of this data for the year 2005, sort it by population and slice off the top 10 countries. Expand the cell below to see how we obtain this subset. We will use this subset in our first few D3 examples.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":61,"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":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":52,"value":"
\n## Selections and Data Binding","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":65,"value":"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 (`
1. `) are marks:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":72,"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') // set CSS class to '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' elemenet\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":76,"value":"$4a","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":68,"value":"// Run this cell to recolor just the first item in the list above. \n// If you are curious rhe randomColor() function was imported as a utility at the end of this document.\nd3.select('li.country').style('color', randomColor()), null","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":84,"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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":86,"value":"Second, and more importantly for our purposes, 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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":93,"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();\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":94,"value":"However, notice that the visualization produced by the cell above 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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":98,"value":"selection = {\n const ol = d3.create('ol');\n return ol.selectAll('li').data(listData);\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":101,"value":"datajoin = html``","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":104,"value":"_Credit: [Mike Bostock](https://bost.ocks.org/mike/join/)_","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":109,"value":"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 DOM element in the original selection.\n\n * The **update** state is a selection that contains _existing_ DOM elements that match a bound data value.\n\n * The **exit** state is a selection that also contains _existing_ DOM 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.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":111,"value":"We 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:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":113,"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 .text(d => `${d.country}: ${d.pop}`) // For data-bound selections, transformation operators can be \n // functions that receive a data value as an input argument.\n return ol.node();\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":115,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":119,"value":"{\n const ol = d3.create('ol');\n \n ol.selectAll('li') // select all list elements (orange circle in diagram above)\n .data(listData) // bind all our data values (blue circle in diagram 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 .text(d => `${d.country}: ${d.pop}`)\n \n return ol.node();\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":121,"value":"##
  Exercise
  \n\nModify 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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":281,"value":"{\n const ol = d3.select(html`
  `);\n \n ol.selectAll('li') \n .data(listData) \n .join('li') \n .text(d => `${d.country}: ${d.pop}`)\n \n return ol.node();\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":126,"value":"{\n const ol = d3.select('ol#enter-update-exit');\n\n // use a new dataset, manipulable with the variables defined below\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 (orange circle above)\n .data(newData) // bind all our data values (blue circle above)\n .join(\n enter => enter.append('li').style('color', 'green'), // hint: add code here\n update => update.style('color', 'blue'), // hint: add code here\n exit => exit.style('color', 'red') // hint: modify code here\n ) \n .text(d => `${d.country}: ${d.pop}`);\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":131,"value":"year = 2005","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":129,"value":"n = 13","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":133,"value":"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 the [next notebook](https://observablehq.com/@stanfordvis/making-d3-charts-interactive), D3's data join makes it more convenient to specify animated transitions as items are entering, updating, or exiting.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":137,"value":"
  \n## A Simple Bar Chart\n\nBefore 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\n##
  Exercise
  \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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":139,"value":"FileAttachment(\"Screen Shot 2020-03-02 at 7.13.09 AM.png\").image()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":142,"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":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":144,"value":"{\n const container = d3.create('div');\n \n // Add code here to generate the bar chart within the container.\n // Use 'div' elements for each bar. \n // Make sure you set some text to each div in order to make sure the bars appear.\n // The 'barData' variable holds the data to visualize as a set\n // of objects with 'key' and 'value' properties.\n \n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":146,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":150,"value":"
  \n## Scale Functions\n\nRather 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://github.com/d3/d3-scale#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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":153,"value":"The current page `width` variable = ${width} px.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":156,"value":"xscale = d3.scaleLinear()\n .domain([0, d3.max(barData, d => d.value)])\n .range([0, width]) ","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":158,"value":"`xscale` is a function that linearly maps an input value to the given range:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":162,"value":"xscale(49)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":164,"value":"We can now use it to scale our bar widths like so:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":167,"value":"{\n const container = d3.create('div');\n\n container.selectAll('div')\n .data(barData)\n .join('div')\n .style('background', 'rebeccapurple')\n .style('border', ' 1px solid white')\n .style('font-size', 'small')\n .style('color', 'white')\n .style('text-align', 'right')\n .style('padding', '10px')\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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":170,"value":"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. Alternatively we can instead use a [color scale](https://github.com/d3/d3-scale-chromatic#d3-scale-chromatic) like so:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":174,"value":"color = 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!","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":176,"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))\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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":178,"value":"$4b","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":183,"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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":185,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":188,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":192,"value":"height = 150","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":194,"value":"yscale = d3.scaleBand()\n .domain(barData.map(d => d.key))\n .range([0, height]) // Try flipping this to [0, height] and see the effect on the bars below.","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":196,"value":"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\nNow we can use our new `yscale` like so:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":199,"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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":201,"value":"With SVG, rotating our bar chart into a column chart becomes much more straightforward than it would have been with HTML.\n\n##
  Exercise
  \nTry changing your bar chart from a horizontal orienration to a vertical orientation below. _Hint: Think about how the scales of a bar chart differ from a column chart._\nThe chart you want to create should look something like this:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":207,"value":"","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":205,"value":"{\n const width = 400;\n const 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 xscale = /* add code here */;\n\n // Redefine the y scale here.\n const yscale = /* 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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":211,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":214,"value":"
  \n## ``: The SVG Group Element\n\n\nSVG'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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":217,"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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":219,"value":"Alright, now that we've met ``, let's get back to the main event!","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":223,"value":"
  \n## Visualizing Scales: Axes & Legends","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":225,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":227,"value":"graphic","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":229,"value":"_Credit: [Mike Bostock](https://observablehq.com/@d3/margin-convention)_","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":234,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":239,"value":"margin = ({top: 10, right: 10, bottom: 20, left: 20})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":241,"value":"Our scales will then use this margin offset to determine their range:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":246,"value":"xMargin = xscale.copy().range([margin.left, width - margin.right])","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":247,"value":"// Remember (0, 0) is the top-left hand corner\nyMargin = yscale.copy().range([height - margin.bottom, margin.top])","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":249,"value":"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!","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":254,"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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":256,"value":"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":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":261,"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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":263,"value":"Our last step is then to merge all our code together, bars + axes:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":267,"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","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":269,"value":"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 the [next notebook](https://observablehq.com/@stanfordvis/making-d3-charts-interactive)!","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":274,"value":"$4c","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":276,"value":"
  \n### Acknowledgements\n\nThis notebook was originally written by 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.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":26,"value":"## Imports","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":29,"value":"import {fromColumns, printTable} from '@uwdata/data-utilities'","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":30,"value":"import {aq, op} from '@uwdata/arquero'","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":33,"value":"import {graphic} from '@d3/margin-convention'","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":36,"value":"datasets = require('vega-datasets')","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":39,"value":"randomColor = () => `#${Math.floor(Math.random()*16777215).toString(16)}`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W4d","stdlib":"1"}} 24:null