31:[] 2f:{"title":"Introduction to D3’s scales","cells":[{"id":0,"value":"md`# Introduction to D3’s scales\n\nWhen, on a print map, 1 cm figures a real distance of 1 km on the terrain, we say that the map has a 1:100,000 scale.\n\nBut scales are not limited to a proportional ratio (or rule of three) between an actual distance and a length on paper. More generally, they describe how an actual dimension of the original data is to be represented as a visual variable. In this sense, scales are one of the most fundamental abstractions of data visualization.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":11,"value":"md`Scales from the [d3-scale](https://github.com/d3/d3-scale) module are functions that take as input the actual value of a measurement or property. Their output can in turn be used to encode a relevant representation.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"d3.scaleLinear()","pinned":true,"hidden":false,"mode":"ojs"},{"id":28,"value":"md`A scale thus maps a physical quantity (or, more generally, an observation), which might be expressed in meters, kilograms, years or seconds, number of horses in a field… to a length or a radius (in screen pixels or print centimeters), a [color](/@d3) (in CSS representation), a [shape](/@d3)…`","pinned":false,"hidden":false,"mode":"ojs"},{"id":104,"value":"md`## Domain and range`","pinned":false,"hidden":false,"mode":"ojs"},{"id":36,"value":"md`A scale has to know from whence this observation comes — and this is called its *domain*; and to what it converts these values — its *range*. For example, if we are observing sales of cheese on a certain day on an Indian market (a number expressed in rupees), and want to display them as bars of a certain length (in pixels), we’ll define the scale this way:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":45,"value":"barLength = d3.scaleLinear()\n .domain([0, 100000])\n .range([0, 400])","pinned":true,"hidden":false,"mode":"ojs"},{"id":64,"value":"md`If we use this scale to draw our chart, sales of 1 *lakh* rupees (₹100,000) will be represented by a rectangle 400 pixels-long.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":49,"value":"md`In this case, the domain is mapped to the range in a linear fashion — and one could write this as a simple function:\n~~~{js}\nfunction barLength(income) {\n return income / 100000 * 4000;\n}\n~~~\n\nD3 scales, however, convey more information than just “converting a quantity to a pixel value.” First, their range and domain can be queried, for example allowing charts to “discover” the beginning and end of an axis by reading these values:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":90,"value":"barLength.domain()","pinned":true,"hidden":false,"mode":"ojs"},{"id":93,"value":"barLength.range()","pinned":true,"hidden":false,"mode":"ojs"},{"id":101,"value":"md`Complete and accurate legends, a notoriously labor-intensive part of data visualization, can even be created automatically from scales, for example with Susie Lu’s [D3-legend](https://d3-legend.susielu.com/) module.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":114,"value":"md`Most scales also offer an inverse method — going from visual variable to the original dimension. This allows interactivity in which the user can, for example, point on a specific point (in screen coordinates), and the application responds with a pop-up window showing a value in rupees:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":119,"value":"barLength.invert(200) // what is the income under the mouse if it sits at 200 pixels?","pinned":true,"hidden":false,"mode":"ojs"},{"id":305,"value":"md`## Non-numeric scales\n\nScales need not be numeric. Their *domain* can be ordinal, and their *range* can be a set of colors, shapes, words…`","pinned":false,"hidden":false,"mode":"ojs"},{"id":125,"value":"md`### Ordinal scales\n\n[d3.scaleOrdinal](https://github.com/d3/d3-scale/blob/master/README.md#ordinal-scales) creates a scale whose domain is a discrete set of values. These can be ordinal (ordered) or categorical (unordered).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":133,"value":"lifeSpan = d3.scaleOrdinal()\n .domain([\"cat\", \"rabbit\", \"dog\"])\n .range([16, 2, 13])","pinned":true,"hidden":false,"mode":"ojs"},{"id":139,"value":"lifeSpan(\"dog\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":156,"value":"md`As a shorthand notation, the previous definition can be written as d3.scaleOrdinal(range) or d3.scaleOrdinal(domain, range):`","pinned":false,"hidden":false,"mode":"ojs"},{"id":161,"value":"d3.scaleOrdinal([16, 13, 2]).domain([\"cat\", \"dog\", \"rabbit\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":164,"value":"d3.scaleOrdinal([\"cat\", \"dog\", \"rabbit\"], [16, 13, 2])","pinned":true,"hidden":false,"mode":"ojs"},{"id":229,"value":"md`### Unknown values`","pinned":false,"hidden":false,"mode":"ojs"},{"id":181,"value":"md`By default, when an ordinal scale is applied to a previously unseen value, it adapts its domain automatically to include the new value. While this might seem arbitrary (and would serve no purpose in the lifeSpan scale that we saw earlier), it is extraordinary useful if we need to apply distinct colors (or shapes or, below, emojis) to different data points, with no initial knowledge of the dataset. When new values come in and the range is exhausted, the ordinal scale cycles on its range to select a new output:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":185,"value":"{\n const emoji = d3.scaleOrdinal().range([\"🎃\", \"👹\", \"🌚\"]);\n\n return [\n emoji(\"1st point\"),\n emoji(\"2nd point\"),\n emoji(\"3rd point\"),\n emoji(\"4th point\"),\n emoji(\"5th point\"),\n emoji(\"6th point\"),\n emoji(\"7th point\")\n ];\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":235,"value":"md`Internally, this behavior is made possible by the combination of two methods: *scale*.unknown, which allows to specify what should be returned for unknown values, and d3.scaleImplicit, which adds unknown values to the domain and associates them with an output. These methods are detailed in the [d3.scaleOrdinal](https://observablehq.com/@d3/d3-scaleordinal) notebook.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":241,"value":"md`### Non-numeric range\n\nA scale can map to numbers but also strings, CSS colors, etc. A common use is a linear scale that maps a number (say, between 0 and 1) to a color (*e.g.* “yellow” to “red”). [CSS color strings](d3-color) are automagically detected and interpolated, which allows to write:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":247,"value":"paint = d3.scaleLinear().range([\"yellow\", \"red\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":250,"value":"paint(0.5) // this must be orange","pinned":true,"hidden":false,"mode":"ojs"},{"id":255,"value":"{\n return html`${d3\n .ticks(0, 1, 20)\n .map(paint)\n .map(\n t =>\n ` `\n )}`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":307,"value":"md`## Numeric scales\n\nThe relationship between a value and the visual variable associated to it is not always linear. If a certain quantity (say, population size of a country) is represented by a colored disk, what should be proportional to the value is the *surface area* of that disk, not its radius. The area is proportional to the square of the radius ${tex`(A = π R^2)`}; conversely the radius — which is what we need to create the shape in SVG — must be proportional to the square root of the value. The dedicated d3.scaleSqrt method creates such a scale:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":310,"value":"population2radius = d3.scaleSqrt() // instead of scaleLinear()\n .domain([0, 2e9])\n .range([0, 300])","pinned":true,"hidden":false,"mode":"ojs"},{"id":323,"value":"population2radius(1.386e9) // China’s 1.386 billion citizens are represented by a circle of radius = 250px","pinned":true,"hidden":false,"mode":"ojs"},{"id":326,"value":"population2radius(127e6) // Japan’s population of 127 millions is represented by a circle of radius = 76px","pinned":true,"hidden":false,"mode":"ojs"},{"id":334,"value":"population2radius(427e3) // Brunei shows up as a small circle","pinned":true,"hidden":false,"mode":"ojs"},{"id":339,"value":"svg`\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":464,"value":"color = d3.scaleOrdinal([\"green\", \"red\", \"blue\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":420,"value":"md`This notebook barely scratches the surface of what can be done with scales. The temporary conclusion and main takeaway is that, by wisely chosing scales, you define the core of your data visualization… and the rest are just practical details of implementation.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":106,"value":"md`---\n## Annex`","pinned":false,"hidden":false,"mode":"ojs"},{"id":14,"value":"d3 = require(\"d3-scale@3\", \"d3-array@2\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":448,"value":"// This documentation is released under the CC BY-SA 4.0 license.\n// https://creativecommons.org/licenses/by-sa/4.0/\nLICENSE = \"cc-by-sa-4.0\"","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}