30:[] 2e:{"title":"d3.scaleOrdinal","cells":[{"id":0,"value":"# d3.scaleOrdinal\n\nOrdinal scales are probably the most used type of scales in D3. Give them a bunch of “things” and a bunch of values, and they will consistently return the same value for the same thing. Even better, you don't have to know in advance which things the scale will encounter, as that correspondence can be built incrementally with incoming data.\n\nFirst, a definition: a scale is said to be **categorical** if its domain is a discrete set, and **ordinal** if that set is ordered. (For d3-scale, this makes no difference: the domain is an array, or iterator, that will be read in the order it is given.) \n\nNow, we’ll see in detail how this works, but let’s start with the most common case — the ordinal coloring scale, using the standard color scheme [d3.schemeCategory10](https://d3js.org/d3-scale-chromatic/categorical#schemeCategory10):","pinned":false,"hidden":false,"mode":"md"},{"id":300,"value":"{\n const color = d3.scaleOrdinal(d3.schemeCategory10);\n return html`

\n ${\"A list of ten words to explore this scale’s domain\"\n .split(/ /)\n .map(\n c => ` ${c} `\n )\n .join(\"\")}`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":358,"value":"color = d3.scaleOrdinal(d3.schemeCategory10)","pinned":true,"hidden":false,"mode":"ojs"},{"id":328,"value":"md`[*ordinal*.domain](https://d3js.org/d3-scale/ordinal#ordinal_domain) sets or reads the scale’s domain. (Caveat: the domain must be composed of numbers or strings, not objects.)`","pinned":false,"hidden":false,"mode":"md"},{"id":330,"value":"setDomain = {\n color.domain(\"A list of ten words to explore this scale’s domain\".split(/ /));\n return color.domain();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":344,"value":"[*ordinal*.range](https://d3js.org/d3-scale/ordinal#ordinal_range) likewise sets or reads the scale’s range (which we initialized with d3.schemeCategory10):","pinned":false,"hidden":false,"mode":"md"},{"id":356,"value":"d3.schemeCategory10","pinned":true,"hidden":false,"mode":"ojs"},{"id":607,"value":"Once a few of its values have been set, we can read its range:","pinned":false,"hidden":false,"mode":"md"},{"id":346,"value":"(setDomain, color.range())","pinned":true,"hidden":false,"mode":"ojs"},{"id":12,"value":"[d3.scaleOrdinal](https://d3js.org/d3-scale/ordinal) creates an ordinal scale, with an empty domain and an empty range. It won’t do much unless we give it some values it can output — which we can do by specifying *scale*.range — or by using the shorthand notation d3.scaleOrdinal(range) — like for example with this palette extracted by Patrick Syme from Werner’s work, and made [au goût du jour by Nicholas Rougeux](https://www.c82.net/werner/#colors):","pinned":false,"hidden":false,"mode":"md"},{"id":16,"value":"werner = {\n replay;\n return d3.scaleOrdinal([`#383867`, `#584c77`, `#33431e`, `#a36629`, `#92462f`, `#b63e36`, `#b74a70`, `#946943`]);\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":32,"value":"When we apply the scale to new data, the scales first checks if it has associated the data to a certain value. If not, it takes a new value from its range, matches it with the incoming data, and returns the value.","pinned":false,"hidden":false,"mode":"md"},{"id":22,"value":"run = {\n const data = \"While the original colors have aged, they have been preserved here as in the original in an effort to faithfully reproduce the guide.\".split(\n / /\n );\n var i = 0;\n\n while (i++ < data.length) {\n const str = data.slice(0, i);\n yield html`

${str\n .map(\n word =>\n `\n ${word}\n `\n )\n .join(\"\")}`;\n werner;\n await Promises.delay(300);\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":113,"value":"At the same time, we can observe how the domain evolves as words arrive. New words get a new color, words that have already been seen (“the”, “original”, “have”…) get the same color as the first time. Finally, when the stock of colors is exhausted (at “aged”), the scale finds new colors by starting again at the beginning of the range. (Click on Replay to reinitialize the scale and start again.)","pinned":false,"hidden":false,"mode":"md"},{"id":122,"value":"viewof replay = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":103,"value":"(run, werner.domain())","pinned":true,"hidden":false,"mode":"ojs"},{"id":561,"value":"## Invert scale\n\nBecause its domain is not fixed, and its range can contain repeated values, an ordinal scale can not be inverted. It is however possible to build a reciprocal ordinal scale like so:","pinned":false,"hidden":false,"mode":"md"},{"id":564,"value":"taint = d3.scaleOrdinal([\"earth\", \"wind\", \"fire\"], [\"green\", \"red\", \"blue\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":566,"value":"invert = d3.scaleOrdinal(taint.range(), taint.domain())","pinned":true,"hidden":false,"mode":"ojs"},{"id":567,"value":"invert(\"green\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":174,"value":"## scaleImplicit\n\nThis magic trick is performed by [d3.scaleImplicit](https://d3js.org/d3-scale/ordinal#scaleImplicit), which is the default value for ordinal scales’ “unknown”. To substitute another method for values that haven’t been declared in the domain, use [*ordinal*.unknown](https://d3js.org/d3-scale/ordinal#ordinal_unknown):","pinned":false,"hidden":false,"mode":"md"},{"id":180,"value":"unknown = d3.scaleOrdinal([0, 1, 2], [\"A\", \"B\", \"C\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":182,"value":"unknown(3)","pinned":true,"hidden":false,"mode":"ojs"},{"id":192,"value":"no_unknown = d3.scaleOrdinal([0, 1, 2], [\"A\", \"B\", \"C\"])\n .unknown(\"…\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":195,"value":"no_unknown(3)","pinned":true,"hidden":false,"mode":"ojs"},{"id":198,"value":"*scale*.unknown with no argument returns the constant used for unknown values. Note that d3.scaleImplicit is a special symbol hardwired in d3’s [source code](https://github.com/d3/d3-scale/blob/master/src/ordinal.js#L11).","pinned":false,"hidden":false,"mode":"md"},{"id":203,"value":"unknown.unknown()","pinned":true,"hidden":false,"mode":"ojs"},{"id":201,"value":"no_unknown.unknown()","pinned":true,"hidden":false,"mode":"ojs"},{"id":212,"value":"## Copy\n\n[*ordinal*.copy](https://d3js.org/d3-scale/ordinal#ordinal_copy) will make a copy of the ordinal scale, with the same settings. This can be useful when you have set a scale on a certain domain, and want to extend it to a new (previously unknown) element, but don't want the scale to remember that element:","pinned":false,"hidden":false,"mode":"md"},{"id":216,"value":"source = d3.scaleOrdinal()\n .domain([0, 1])\n .range([\"red\", \"blue\", \"green\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":553,"value":"{\n const a2 = source.copy()(2);\n const a3 = source.copy()(3); // without the copy, a3 would go back to \"red\"\n return { a2, a3 };\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":382,"value":"Note that setting the range will reset the internal associations, in effect resetting the scale.","pinned":false,"hidden":false,"mode":"md"},{"id":380,"value":"{\n const scale = d3.scaleOrdinal();\n\n scale.range([\"first\", \"second\"]);\n const before = scale(\"A\") + \", \" + scale(\"B\");\n\n scale.range([\"1st\", \"2nd\"]);\n const after = scale(\"A\") + \", \" + scale(\"B\");\n\n return { before, after };\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":247,"value":"## Colors & Symbols\n\nColor palettes are a quite common use case for ordinal ranges. You are encouraged to create your own, by hand or using [one of the many tools available](https://projects.susielu.com/viz-palette), but you can also use the list of color schemes provided by [d3-scale-chromatic](https://observablehq.com/collection/@d3/d3-scale-chromatic).","pinned":false,"hidden":false,"mode":"md"},{"id":445,"value":"{\n const color = d3.scaleOrdinal(d3.schemePaired);\n return html`

\n ${\"A list of twelve words to explore d3 schemePaired color scheme !\"\n .split(/ /)\n .map(\n c => ` ${c} `\n )\n .join(\"\")}`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":456,"value":"A useful range for an ordinal scale can be a set of symbols that will used to draw shapes, like for instance [d3.symbols](https://d3js.org/d3-shape/symbol).","pinned":false,"hidden":false,"mode":"md"},{"id":461,"value":"{\n const symbols = d3.scaleOrdinal().range(d3.symbols),\n color = d3.scaleOrdinal(d3.schemePaired),\n height = 200,\n symbol = d3.symbol().size(200),\n data = d3.range(500).map(i => ({\n x: width * Math.random(),\n y: height * Math.random(),\n s: Math.floor(9 * Math.random()),\n c: Math.floor(20 * Math.random())\n })),\n paths = data.map(\n d =>\n ``\n );\n\n return svg``;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":407,"value":"## Iterators\n\nd3.scaleOrdinal’s domain and range can be provided as iterators, for example if we have two [Javascript Maps](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), one giving the atomic number of carbon, hydrogen and oxygen, and the second the associated color:","pinned":false,"hidden":false,"mode":"md"},{"id":413,"value":"atoms = new Map([[\"C\", 12], [\"H\", 1], [\"O\", 16]])","pinned":true,"hidden":false,"mode":"ojs"},{"id":422,"value":"colors = new Map([[\"C\", \"black\"], [\"H\", \"white\"], [\"O\", \"blue\"]])","pinned":true,"hidden":false,"mode":"ojs"},{"id":408,"value":"m = d3.scaleOrdinal()\n .domain(atoms.keys())\n .range(colors.values())","pinned":true,"hidden":false,"mode":"ojs"},{"id":426,"value":"m(\"O\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":137,"value":"Conversely, this exports an ordinal scale as a Map:","pinned":false,"hidden":false,"mode":"md"},{"id":109,"value":"new Map(m.domain().map(d => [d, m(d)]))","pinned":true,"hidden":false,"mode":"ojs"},{"id":619,"value":"---\n\n## Appendix\n\nThanks to [Daniel Ortea](/@d-ortea) and [Yuri Vishnevsky](/@yurivish) for suggestions.","pinned":false,"hidden":false,"mode":"md"},{"id":19,"value":"d3 = require(\"d3-scale@3\", \"d3-scale-chromatic@2\", \"d3-shape@2\", \"d3-array@2\")","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W30","stdlib":"1","titling":"auto"}