29:null 2a:["$","title",null,{"children":"Introduction to D3.js | Sophie Engle | Observable"}] 2f:T526,md` ## Getting Started Before we get started, I recommend to get a little more comfortable with [Observable](/) notebooks. A great way to do that is to look at these notebooks about notebooks: 1. [Introduction to Notebooks](https://beta.observablehq.com/@mbostock/introduction-to-notebooks): This notebook introduces notebooks, including how to interact with and edit cells. 1. [Introduction to HTML](https://beta.observablehq.com/@mbostock/introduction-to-html): This notebook demonstrates the different types of cells available in Observable notebooks. 1. [Introduction to Code](https://beta.observablehq.com/@mbostock/introduction-to-code): This notebook demonstrates how to write and share code in notebooks. 1. [Standard Library](https://beta.observablehq.com/@mbostock/standard-library): This notebook serves as a cheat sheet for Observable notebooks. You should also get familiar with [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML), [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG), and [Markdown](https://guides.github.com/features/mastering-markdown/). This notebook will cover those basics as we encounter them, but it is far from comprehensive. `30:T4ad,{ let height = 100; const svg = d3.select(DOM.svg(config.outerWidth, height)); let g = svg.append("g"); g.call(xAxis); g.attr("transform", "translate(" + margin.left + "," + (height - margin.bottom) + ")"); let plot = svg.append("g"); plot.attr("transform", "translate(" + margin.left + ",0)"); // first we have to bind data to rect elements let bars = plot.selectAll("rect").data(letters); // d3 uses an enter, update, and exit selection (see board drawing) // enter is all of the new data that is unbound // update is all of the data already bound (we have none of this) // exist is all of the rect that no longer have bound data (we also have none of this) let barHeight = x.bandwidth(); bars.enter().append("rect") // we must now scale our letter to an x pixel position .attr("x", function(d) { return x(d); }) // temporarily we will used a fixed position, but where should it be? .attr("y", height - margin.bottom - barHeight) // the width of our bar is determined by our band scale .attr("width", x.bandwidth()) // temporarily we will used a fixed height .attr("height", barHeight); return svg.node(); }31:[] 2d:{"id":"28ba93f58fb82f49","slug":null,"title":"Introduction to D3.js","thumbnail":"31e355bc31ceed6e5d3a620c0fb36a3ee72b03b3e120204c28872ad3e25efa5e","access_level":"unlisted","create_time":"$D2019-01-31T03:55:51.026Z","update_time":"$D2025-10-06T19:38:52.316Z","view_time":null,"first_public_time":null,"fork":false,"stars":0,"starred":false,"owner":{"type":"team","id":"5daeb3b295f61c60","login":"sjengle","name":"Sophie Engle","avatar_url":"https://avatars-next.observableusercontent.com/ba843dbbe22e6effd001e1baf75052c3b58b856ba20f2250b1152f6fc72c5648","tier":"starter_2024"},"version":411,"publish_version":411,"role":null,"authored":false,"authors":[{"type":"individual","id":"cd2851261031ef7e","login":"sjengle","name":"Sophie Engle","avatar_url":"https://avatars-next.observableusercontent.com/ba843dbbe22e6effd001e1baf75052c3b58b856ba20f2250b1152f6fc72c5648","tier":null}],"members":[{"type":"individual","id":"cd2851261031ef7e","login":"sjengle","name":"Sophie Engle","avatar_url":"https://avatars-next.observableusercontent.com/ba843dbbe22e6effd001e1baf75052c3b58b856ba20f2250b1152f6fc72c5648","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":2,"collection":null,"type":"notebook","body":{"title":"Introduction to D3.js","cells":[{"id":0,"value":"md`# Introduction to D3.js\n\nThis notebook provides a quick introduction to [D3.js](https://d3js.org/) and [Observable](https://beta.observablehq.com/) notebooks.\n\n

This notebook is based off the [Letter Count Bar Chart](https://bl.ocks.org/sjengle/1e23258249638a508426470a48ff2924) example, except updated for D3v5 and Observable.

\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":11,"value":"md`\nFor this example, we will create a simple bar chart that displays the letter count of a text file.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":148,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":25,"value":"$2f","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":146,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":18,"value":"md`\n## Loading D3\n\nWe first need to load the [D3.js](https://d3js.org/) library. \n\nWell, *actually*, that is not quite true. Observable [runs cells independently of their order in the notebook](https://beta.observablehq.com/@mbostock/how-observable-runs), so we could place this code at the bottom of the notebook! Pretty neat, huh?\n\nWe will do it below only because I wanted to talk about it here. Observable makes it easy to [import open source JavaScript modules](https://beta.observablehq.com/@tmcw/introduction-to-require) in your notebooks:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":46,"value":"// this cell is pinned so you can view the code\n// the line below will load d3v5\nd3 = require('d3@5')","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":50,"value":"d3.version","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":56,"value":"md`\nOh geeze, D3 is at version 5 already? \n\nIt is important to note that [version 5 only supports recent browsers](https://github.com/d3/d3/wiki#supported-environments), such as Chrome, Edge, Firefox and Safari. Versions 4 and below also supports IE 9+, but who wants to use version 4 when exciting stuff like this is happening in version 5:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":62,"value":"tweet(\"1089948750879936512\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":109,"value":"md`\nIf you are not already familiar with D3, it might not make sense just how cool the [selection.join()](https://beta.observablehq.com/@d3/selection-join) addition is... but it will make our future code more streamlined.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":150,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9,"value":"md`\n## Loading Data\n\nOkay, lets attempt to load some data. For this example, our data will initially be a simple text file hosted at:\n\n<${gist}>\n\nThe content of this text file is:\n\n\\`\\`\\`\n${peter}\n\\`\\`\\`\n\nYes, *I know*. This is such a small file that the text could have been defined directly in this notebook. I mean, I put the ENTIRE FILE above. Regardless, I want to show you how to load data!\n\n

Psst, I didn't copy/paste the link or text file above. I used some notebook magic to load it and embed it in this text!

\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":91,"value":"md`\nBack to the matter at hand. To load this text file, we will use the [d3.text()](https://github.com/d3/d3-fetch/blob/master/README.md#text) function from the [d3-fetch](https://github.com/d3/d3-fetch) module.\n\nIn the code below, it might look like this happens instantly. However, [fetching the data over the network happens *asynchronously*](https://beta.observablehq.com/@mbostock/introduction-to-promises). Thankfully, the notebook takes care of waiting for the data and updating all the cells that uses it.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":17,"value":"// \ngist = 'https://gist.githubusercontent.com/sjengle/1e23258249638a508426470a48ff2924/raw/91574c21eeeda6a31ab82863f1697b336d2460a1/peter.txt'","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":87,"value":"peter = d3.text(gist);","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":152,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":112,"value":"md`\n## Processing Data\n\nWe want to process the text into a letter count, which we will eventually visualize as a bar chart. \n\nWe will define several functions for the letter count, allowing us to reuse this code througout the notebook. There are [several ways to define a function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) in JavaScript, but in this notebook [we will stick to one approach](https://beta.observablehq.com/@mbostock/introduction-to-code) for defining our functions.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":129,"value":"md`\nBefore we calculate a letter count, we want to remove anything that isn't a letter from our input text. This is a good opportunity to demonstrate how to use [regular expressions in Javascript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp):\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":131,"value":"function keepLetters(input) {\n let notLetter = /[^a-z]/g;\n return input.toLowerCase().replace(notLetter, \"\");\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":135,"value":"keepLetters(\"Hello, world!\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":137,"value":"md`\nFor our actual letter count code, we will take advantage of the [d3.map()](https://github.com/d3/d3-collection/blob/master/README.md#map) implementation and [for loops](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for) in JavaScript:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":113,"value":"function countLetters(input) {\n let text = keepLetters(input);\n let count = d3.map();\n \n for (var i = 0; i < text.length; i++) {\n let letter = text[i];\n\n if (count.has(letter)) {\n count.set(letter, count.get(letter) + 1);\n }\n else {\n count.set(letter, 1);\n }\n } \n \n return count;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":116,"value":"// calculate the letter count map and show the entries\ncountLetters(\"Book-Keeper\").entries();","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":176,"value":"md`\nLooking good! Now we can get the letter count of our data:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":174,"value":"letterCount = countLetters(peter);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":185,"value":"table(letterCount.entries(), {sortable: true})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":170,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":172,"value":"md`\n## Visualizing Data\n\n\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":202,"value":"md`\nWe will use [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) elements, which are **s**calable **v**ector **g**raphics well-suited for interactive visualizations. However, SVGs can have performance issues. We will not need to worry about that for this example.\n\nLets create our first SVG:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":198,"value":"html`\n`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":204,"value":"md`\nWe can style the SVG using [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS). We will also use CSS id and class selectors in D3 later too, so it is important to be familiar with CSS.\n\nHowever, the exact style attributes we use depend on whether the element is outside or inside the \\`svg\\` tags. The actual \\`svg\\` tag is part of the HTML specification, and we can use standard HTML/CSS styling to change its background color and border. Everything between the \\`svg\\` tags is part of the SVG specification. This means instead of changing a \\`background-color\\` attribute, we change the \\`fill\\` instead:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":216,"value":"html`\n

See the stylesheet defined below.

\n\n`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":224,"value":"md`\nOur SVG might not look too interesting, but we can actually use that blank SVG to figure out how much space we have for our bar chart.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":239,"value":"margin = ({\n left: 20,\n right: 20,\n top: 20,\n bottom: 30\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":197,"value":"config = {\n let svg = d3.select(\"svg#first\");\n let bounds = svg.node().getBoundingClientRect();\n\n return {\n outerWidth: Math.floor(bounds.width),\n outerHeight: Math.floor(bounds.height),\n // the inner plot area\n innerWidth: Math.floor(bounds.width - margin.right - margin.left),\n innerHeight: Math.floor(bounds.height - margin.top - margin.bottom)\n };\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":193,"value":"md`\nNow that we have some idea of how much space we have, we can setup our scales. We use scales to encode the data. We need to somehow scale our data (domain) to a visual attribute (range). For our bar chart, we will use the following encoding:\n\n| Domain | Range | Description |\n|:-------|:------|:------------|\n| Letter | Horizontal (*x*) Position | Determines the *x* position and *width* for each letter's bar. |\n| Count | Vertical (*y*) Position | Determines the *y* position and *height* of each letter's bar. |\n\nWe will start with scaling letters to *x* positions and widths. For this, we will use a band scale:\n\n

Image: [Band Scales](https://github.com/d3/d3-scale/blob/master/README.md#band-scales)

\n\nWhenever setting up a scale, we have to specify the domain (the input data) and the range (the output attribute):\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":189,"value":"x = d3.scaleBand()\n .domain(letters)\n .range([0, config.innerWidth])\n .paddingInner(0.1); // space between bars","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":270,"value":"md`\nUsing this scale, we can calculate that \\`x('a') = ${x('a')}\\`, \\`x('b') = ${x('b')}\\`, and \\`x('z') = ${x('z')}\\`. We will use those as *x* pixel values when drawing our bars.\n\nWe will also need an axis line, tick marks, and tick labels. Thankfully, this functionality is built-in to D3:\n`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":280,"value":"xAxis = d3.axisBottom(x);","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":318,"value":"md`\nNow we have everything we need to draw the axis. Lets just try it out:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":283,"value":"{\n let height = 100;\n \n const svg = d3.select(DOM.svg(config.outerWidth, height));\n \n let g = svg.append(\"g\");\n g.call(xAxis);\n g.attr(\"transform\", \"translate(\" + margin.left + \",\" + (height - margin.bottom) + \")\");\n \n return svg.node();\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":269,"value":"md`\nFinally, we've done... *something*. Lets see if we can do something more? How about drawing a bar in each position with a fixed height. This is harder than it seems, since the *y* direction is flipped. \n\n*Huh?*\n\nThe [coordinate system](https://developer.mozilla.org/en-US/docs/Web/CSS/CSSOM_View/Coordinate_systems) places the origin (0, 0) in the top-left corner. The *x* values increase as you move right, but *y* values increase as you move down! Think about graphics coordinate systems as accessing a two dimensional array of pixels, and it will start to make more sense. \n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":326,"value":"$30","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":363,"value":"md`\nOkay, things got weird *fast*, and we are only half way there! Next, we have to map the letter count to bar height. This is a little different... we no longer want to map a category-like input to a band as output.\n\nSo, we will use a [continuous linear scale](https://github.com/d3/d3-scale/blob/master/README.md#continuous-scales) instead. It takes a number as input, and produces a different number as output.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":373,"value":"countMax = d3.max(letterCount.values())","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":365,"value":"y = d3.scaleLinear()\n .domain([0, countMax]) // always start at 0!\n .range([config.innerHeight, 0]) // remember y is flipped!\n .nice(); // rounds the domain a bit for nicer output","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":383,"value":"yAxis = d3.axisLeft(y);","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":369,"value":"md`\nUsing this scale, we can calculate that \\`y(0) = ${y(0)}\\`, \\`y(${countMax/2}) = ${y(countMax/2)}\\`, and \\`y(${countMax}) = ${y(countMax)}\\`. We will use those as *y* pixel values when drawing our bars.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":387,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":389,"value":"md`\n## Visualizing Data\n\nAfter that long journey, we are finally able to build our bar chart. Lets put it all together:\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":393,"value":"chart = {\n const svg = d3.select(DOM.svg(config.outerWidth, config.outerHeight));\n \n let g = svg.append(\"g\");\n g.call(xAxis);\n g.attr(\"transform\", \"translate(\" + margin.left + \",\" + (config.innerHeight) + \")\");\n \n let plot = svg.append(\"g\");\n plot.attr(\"transform\", \"translate(\" + margin.left + \",0)\");\n \n // now we have to use our real data\n let bars = plot.selectAll(\"rect\").data(letterCount.entries());\n \n bars.enter().append(\"rect\")\n // and we have to update how we access our data\n .attr(\"x\", function(d) { return x(d.key); })\n .attr(\"y\", function(d) { return y(d.value); })\n .attr(\"width\", x.bandwidth())\n // here it gets weird... how do we set the bar height?\n .attr(\"height\", function(d) { return config.innerHeight - y(d.value); });\n \n return svg.node();\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":154,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":66,"value":"md`\n## Appendix\n\nRemember how I mentioned imports did not need to happen before the code that uses them? Well here are the imports (and other stuff) I didn't want to talk about earlier! They are all moved out of the way as to not interrupt the rest of the text.\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":59,"value":"// this is an example of embedding code from other notebooks!\n// see: https://beta.observablehq.com/@mbostock/tweet\nimport {tweet} from \"@mbostock/tweet\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":178,"value":"// see: https://beta.observablehq.com/@tmcw/tables\nimport {table} from \"@tmcw/tables@444\"","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":121,"value":"letters = \"abcdefghijklmnopqrstuvwxyz\".split(\"\");","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W31","stdlib":"1","titling":"auto"}} 2e:"$2d:body"