30:[{"id":"071f5c8df7a2e4458ba1720fde560e5895629ef6a6769814d7d9f0bb5f57a721fcaeb395df6e39af9cd50cbbb8b4327357883d729e8a37e601cd7525d7658b43","href":"https://static.observableusercontent.com/files/071f5c8df7a2e4458ba1720fde560e5895629ef6a6769814d7d9f0bb5f57a721fcaeb395df6e39af9cd50cbbb8b4327357883d729e8a37e601cd7525d7658b43","name":"Pulalius.jpg","type":"image/jpeg","lastModified":1572395484602.38,"size":189020}] 2e:{"title":"d3.scaleLinear","cells":[{"id":0,"value":"# d3.scaleLinear\n\n[d3.scaleLinear](https://d3js.org/d3-scale/linear#scaleLinear) constructs creates a [scale](https://observablehq.com/@d3/introduction-to-d3s-scales) with a linear relationship between input and output.","pinned":false,"hidden":false,"mode":"md"},{"id":7,"value":"lin = d3.scaleLinear()","pinned":true,"hidden":false,"mode":"ojs"},{"id":17,"value":"By default, the scale’s *domain* and *range* are both the interval [0,1], and the scale can be expressed as the identity function: *y* = *x*. This is what happens if we measure, say, a crab’s span in meters, and want to represent it by a line of the same length: the crab is 0.09 m wide, and the line 0.09 m long. From domain to range, the numbers are unchanged but, conceptually, the quantity has been transformed from an observation (in the domain) to a visual variable (in the range).","pinned":false,"hidden":false,"mode":"md"},{"id":731,"value":"

Fossil crab *Pulalius Vulgaris*. Photo: [Jason Boddy](https://fr.wikipedia.org/wiki/Fichier:Pulalius.jpg)

","pinned":false,"hidden":false,"mode":"md"},{"id":39,"value":"More generically, linear scale transforms can be computed as ${tex`y = ax+b`}, where *a* is the slope and *b* is the y intersect, *i.e.* the value when *x*= 0. But this is not how we will create them: rather, we’ll specify their range and domain as two intervals — the slope and intersect will be determined in such a way that the start of the domain is mapped to the start of the range, and the end of the domain is mapped to the end of the range.\n\nTo represent a distance by a proportional length:","pinned":false,"hidden":false,"mode":"md"},{"id":51,"value":"run2pixels = d3.scaleLinear()\n .domain([0, 42.195]) // unit: km\n .range([0, 600]) // unit: pixels","pinned":true,"hidden":false,"mode":"ojs"},{"id":56,"value":"run2pixels(0) // The start line","pinned":true,"hidden":false,"mode":"ojs"},{"id":110,"value":"run2pixels(42.195) // The distance of a full marathon is 42.195 km; represented by 600 pixels","pinned":true,"hidden":false,"mode":"ojs"},{"id":60,"value":"run2pixels(10 * 1.609344) // 10 miles","pinned":true,"hidden":false,"mode":"ojs"},{"id":67,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":140,"value":"_Although converting miles to kilometers (as we did in the previous cell) is a linear transform, it is *not* a scaling operation, as it doesn’t change the nature of the physical quantity. This highlights the importance of making sure we know in what unit we are working. Usually, the domain will be in the observation’s unit (Celsius degrees, US dollars, seconds…), and the range in screen or print unit (pixels, millimeters… or even CSS colors)._","pinned":false,"hidden":false,"mode":"md"},{"id":153,"value":"### A flipped range\n\nThe domain and range do not need to start at 0. This chart of global temperature trends (click to open it in a new window) might use a vertical scale defined as:\n~~~\ny = d3.scaleLinear()\n .domain(d3.extent(data, d => d.value))\n .range([height, 0])\n~~~\n","pinned":false,"hidden":false,"mode":"md"},{"id":166,"value":"Instead of trying to set *a* and *b* so that the points fit the page, using a scale definition enables the designer to explicitly convey their intent:\n- the graph should cover a vertical *height*;\n- the highest temperatures should be towards the top of the screen;\n- the available vertical space should enclose all values in the data domain’s [extent]() (*i.e.* minimum and maximum).\n\nYou might have remarked that the range is “flipped”, in the sense that it goes from *height* to 0. This is very common when using canvas or SVG to draw our visualization: in these two systems the coordinates are pointing down, from top to bottom. As we usually expect the minimum value to be placed “lower” on the image than the maximal value, the scale’s range will be described by a flipped interval.","pinned":false,"hidden":false,"mode":"md"},{"id":174,"value":"### Nice bounds\n\nThe exact snippet of code in the temperature trends example is, in fact, a bit more complete.\n\nFirst, it adds margins to the scale, so that the circle marks are not too close to the edge of the SVG container. (The minimal and maximal temperatures should not be drawn with a center at coordinates equal to 0 or to height — otherwise they would show as half-circles).","pinned":false,"hidden":false,"mode":"md"},{"id":162,"value":"~~~js\ny = d3.scaleLinear()\n .domain(d3.extent(data, d => d.value)).nice()\n .range([height - margin.bottom, margin.top])\n~~~","pinned":false,"hidden":false,"mode":"md"},{"id":187,"value":"Second, it adds a call to *scale*.nice, which allows to materialize tick marks above and below the extent of the temperature anomaly values (in this case, +1.4°C and -0.8°C). *scale*.nice enlarges the domain’s interval in such a way that its minimum and maximum bounds are [nicely-rounded](https://observablehq.com/@d3/d3-ticks) values, *i.e.* multiples of 2, 5 and powers of 10. This ensures that the vertical axis will be properly labeled.\n\nThis example shows how the scale definition is much more than a way to position the marks. Indeed, the horizontal and vertical [axes](https://d3js.org/d3-axis) of the chart are drawn exclusively by reading the horizontal and vertical scales. Their positions, ticks and labels are behaving accordingly — this saves time, but also guarantees that, when one changes the height of the chart, or when new data arrives with higher temperatures, everything will adapt in a consistent manner.","pinned":false,"hidden":false,"mode":"md"},{"id":554,"value":"### Round ranges\n\n[*scale*.rangeRound](https://d3js.org/d3-scale/linear#linear_rangeRound) sets the range as *scale*.range, while making sure that the values returned will be integers. Useful for representing data with discrete elements. Here's an example where a grade (D to A) will be associated with the percentage of correct answers to a test:","pinned":false,"hidden":false,"mode":"md"},{"id":557,"value":"grades = d3.scaleLinear().rangeRound([0, 3])","pinned":true,"hidden":false,"mode":"ojs"},{"id":574,"value":"grades(63 / 100)","pinned":true,"hidden":false,"mode":"ojs"},{"id":562,"value":"[\"D\", \"C\", \"B\", \"A\"][grades(63 / 100)]","pinned":true,"hidden":false,"mode":"ojs"},{"id":583,"value":"Or, the number of children in a class with an occupancy rate of 90% and a maximum of 46 pupils:","pinned":false,"hidden":false,"mode":"md"},{"id":585,"value":"children = d3.scaleLinear().rangeRound([0, 46])","pinned":true,"hidden":false,"mode":"ojs"},{"id":587,"value":"children(90 / 100)","pinned":true,"hidden":false,"mode":"ojs"},{"id":595,"value":"Note: *scale*.rangeRound(*range*) is a shortcut notation for *scale*.range(*range*).interpolate(d3.interpolateRound). See [*scale*.interpolate](#interpolate) below.","pinned":false,"hidden":false,"mode":"md"},{"id":382,"value":"### Piecewise scales\n\nIf the domain is a list of more than 2 numbers, multiple segments are considered, and each segment is matched to the corresponding numbers in the domain, resulting in a continuous piecewise interpolation:","pinned":false,"hidden":false,"mode":"md"},{"id":398,"value":"piecewiseScale = d3.scaleLinear()\n .domain([0, 100, 200, 300, 400])\n .range([220, 200, 100, 200, 150]) // add + Math.sin(now / 1000) * 50 to one of these for animation","pinned":true,"hidden":false,"mode":"ojs"},{"id":406,"value":"results in the following curve:","pinned":false,"hidden":false,"mode":"md"},{"id":401,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":644,"value":"The piecewise linear scale is closely related to the piecewise interpolation method: [d3.piecewise](https://observablehq.com/@d3/d3-piecewise).","pinned":false,"hidden":false,"mode":"md"},{"id":215,"value":"### Non-numeric range\n\nThe range of linear scales (as well as of other types of [continuous scales](https://observablehq.com/@d3/continuous-scales)) is usually an interval between two real numbers; but it can also be of a non-numeric type, the most useful example being the color scales. To create a color range, one simply gives the start and end colors (or more for a piecewise scale).","pinned":false,"hidden":false,"mode":"md"},{"id":377,"value":"crayons = d3.scaleLinear()\n .domain([-1, 0, 1])\n .range([\"orange\", \"white\", \"green\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":386,"value":"{\n return html`${d3\n .ticks(-1, 1, 20)\n .map(crayons)\n .map(\n t =>\n ` `\n )}`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":374,"value":"This idea generalizes with [interpolators](https://observablehq.com/@d3/d3-interpolate), which can be set, for continuous scales, by calling *scale*.interpolate (see [below](#interpolate)).","pinned":false,"hidden":false,"mode":"md"},{"id":604,"value":"The range can also be made of [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) objects, allowing a scale to transform a number into a date:","pinned":false,"hidden":false,"mode":"md"},{"id":607,"value":"date = d3.scaleLinear()\n .range([new Date(\"2009-01-01T00:00:00\"), new Date(\"2009-12-31T23:59:59\")])","pinned":true,"hidden":false,"mode":"ojs"},{"id":610,"value":"date(0.5)","pinned":true,"hidden":false,"mode":"ojs"},{"id":615,"value":"days = d3.scaleLinear().range([new Date(\"2009-01-01\"), new Date(\"2009-12-31\")])","pinned":true,"hidden":false,"mode":"ojs"},{"id":616,"value":"days(0.5)","pinned":true,"hidden":false,"mode":"ojs"},{"id":627,"value":"See [d3.scaleTime](https://observablehq.com/@d3/d3-scaletime) for the converse operation.","pinned":false,"hidden":false,"mode":"md"},{"id":217,"value":"### Clamping\n\n*scale*.clamp enforces strict bounds on the domain. We’ve described the scale, so far, as a function of the form *y = ax + b*. But there are cases when the odd data point or input that is outside the domain must *not* result in a value outside the range — which this formula might produce.\n\nConsider, for example, a linear scale that defines the length of a bar representing a certain quantity. If an irregular data point arrives with a negative quantity, the bar should be of length = 0, and not some number below 0 — which would result in an error in the SVG.\n\nSimilarly, if a value exceeds the expected maximum of the domain, it might be desirable to limit the output to the range’s maximum. An example could be a scale that encodes an opacity — a number that should be between 0 and 1.","pinned":false,"hidden":false,"mode":"md"},{"id":239,"value":"opacity = d3.scaleLinear()\n .domain([0, 10])\n .range([0, 1])\n .clamp(true) // try with false instead","pinned":true,"hidden":false,"mode":"ojs"},{"id":245,"value":"opacity(-1) // -1 is outside the domain!","pinned":true,"hidden":false,"mode":"ojs"},{"id":248,"value":"opacity(15) // 15 is outside the domain!","pinned":true,"hidden":false,"mode":"ojs"},{"id":259,"value":"That property is readable:","pinned":false,"hidden":false,"mode":"md"},{"id":256,"value":"opacity.clamp()","pinned":true,"hidden":false,"mode":"ojs"},{"id":224,"value":"### Unknown\n\n*scale*.unknown sets the return value of the scale when the input value is unknown (typically NaN, undefined, or a string such as \"No Data\", that cannot be transformed into a number). By default, the unknown value is undefined, but it's possible to set it to a different constant, to represent unavailable data:","pinned":false,"hidden":false,"mode":"md"},{"id":288,"value":"paint = d3.scaleLinear()\n .range([\"yellow\", \"red\"])\n .unknown(\"#ccc\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":273,"value":"paint(NaN)","pinned":true,"hidden":false,"mode":"ojs"},{"id":323,"value":"values = [NaN].concat(d3.ticks(0, 1, 20))","pinned":false,"hidden":false,"mode":"ojs"},{"id":321,"value":"{\n return html`${values\n .map(paint)\n .map(\n t =>\n ` `\n )}`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":299,"value":"That property is readable:","pinned":false,"hidden":false,"mode":"md"},{"id":301,"value":"paint.unknown()","pinned":true,"hidden":false,"mode":"ojs"},{"id":226,"value":"### Invert\n\n*scale*.invert gives an input value that would result in the value. As described in the introduction to scales, inverse values are useful to enable interactivity, so that when the user moves points at a certain screen location, the application infers the underlying value.\n\nNot many surprises here, but note that non-numeric scales (such as a scale with a color range) are *not* invertible:","pinned":false,"hidden":false,"mode":"md"},{"id":349,"value":"paint.invert(\"red\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":365,"value":"Inverted clamped scales are clamped to the domain:","pinned":false,"hidden":false,"mode":"md"},{"id":352,"value":"opacity.clamp(true).invert(-1)","pinned":true,"hidden":false,"mode":"ojs"},{"id":541,"value":"Finally, the invert of piecewise scales works as expected if the scale is monotonous. If there are several solutions, such as with this scale that establishes an opacity that increases when the (positive or negative) value is away from 0, then the results might be unexpected:","pinned":false,"hidden":false,"mode":"md"},{"id":508,"value":"d3.scaleLinear()\n .domain([-30, 0, 30])\n .range([1, 0, 1])\n .clamp(true)\n .invert(0.4)","pinned":true,"hidden":false,"mode":"ojs"},{"id":652,"value":"### Interpolate\n\n[*scale*.interpolate](https://d3js.org/d3-scale/linear#linear_interpolate) allows to set an [interpolation method](https://observablehq.com/@d3/d3-interpolate) for the scale.\n\nA traditional use-case is for color scales, where we want to [use a better color space](https://observablehq.com/@d3/working-with-color) than the default (interpolateRgb), to have more vivid intermediary colors.\n\nAnother common use-case is to set [d3.interpolateRound](https://observablehq.com/@d3/d3-interpolatenumber), instead of the default interpolateNumber, in order to generate only integer values:","pinned":false,"hidden":false,"mode":"md"},{"id":658,"value":"scaleRound = d3.scaleLinear()\n .range([0, 960])\n .interpolate(d3.interpolateRound)","pinned":true,"hidden":false,"mode":"ojs"},{"id":662,"value":"scaleRound(1 / 3)","pinned":true,"hidden":false,"mode":"ojs"},{"id":667,"value":"By creating your own interpolation method, you can specify, for example, a linear scale that returns numbers with one decimal:","pinned":false,"hidden":false,"mode":"md"},{"id":670,"value":"scaleDecimal = d3.scaleLinear()\n .range([0, 960])\n .interpolate(function(a, b) {\n const c = b - a;\n return function(t) {\n return +(a + t * c).toFixed(1);\n };\n })","pinned":true,"hidden":false,"mode":"ojs"},{"id":672,"value":"scaleDecimal(2 / 7)","pinned":true,"hidden":false,"mode":"ojs"},{"id":683,"value":"The interpolation method is also readable:","pinned":false,"hidden":false,"mode":"md"},{"id":681,"value":"scaleDecimal.interpolate()","pinned":true,"hidden":false,"mode":"ojs"},{"id":205,"value":"### Shorthand notation\n\none can indicate the range, or (domain, range) directly when creating a *linearScale*:\n\n~~~js\nconst x = d3.scaleLinear([0, 960]);\nconst color = d3.scaleLinear([10, 100], [\"brown\", \"steelblue\"]);\n~~~","pinned":false,"hidden":false,"mode":"md"},{"id":190,"value":"## Identity\n\n[d3.scaleIdentity](https://d3js.org/d3-scale/linear#scaleIdentity) — which maps a domain onto itself — is a particular case of linear scale. It can be useful in some cases, for example with [d3-zoom](https://d3js.org/d3-zoom) when working with values that are already expressed in pixel coordinates.","pinned":false,"hidden":false,"mode":"md"},{"id":12,"value":"---\n\nThanks to [@fiorins](/@fiorins) for suggestions.","pinned":false,"hidden":false,"mode":"md"}],"files":"$W30","stdlib":"1","titling":"auto"}