30:Tb01,{ const range = scale.range(); const fontSize = width > 500 ? "14px" : "10px"; return svg``; }31:[] 2e:{"title":"d3.scaleBand","cells":[{"id":0,"value":"# d3.scaleBand\n\nBand scales are convenient for charts with an ordinal or categorical dimension.\n\nIn the following [bar chart](https://observablehq.com/@d3/bar-chart), showing the relative frequency of each letter in the English language, the horizontal positions of the bars is given by a band scale. The domain is the list of letters (sorted in descending frequency order). The range — the chart’s width in pixels — is evenly distributed among the letters, which are separated by a small gap.","pinned":false,"hidden":false,"mode":"md"},{"id":12,"value":"import {chart} from \"@d3/bar-chart\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":15,"value":"chart","pinned":true,"hidden":false,"mode":"ojs"},{"id":32,"value":"[d3.scaleBand](https://d3js.org/d3-scale/band#scaleBand) offers the following methods to create this type of scales. By default, given a domain of a certain length (an array or an iterator) and a continuous range [start, end], it will divide the range evenly between the elements of the domain.","pinned":false,"hidden":false,"mode":"md"},{"id":37,"value":"quarter = d3\n .scaleBand()\n .domain([\"one\", \"two\", \"three\", \"four\"])\n .range([0, 100])","pinned":true,"hidden":false,"mode":"ojs"},{"id":48,"value":"The scale defined above—under the name quarter— can then be applied to the elements of the domain, and returns the _start_ of the band:\n\n

\n\n| _v_ | quarter(_v_) |\n|---------|-------------------|\n| one |${quarter(\"one\")} |\n| two |${quarter(\"two\")} |\n| three |${quarter(\"three\")}|\n| four |${quarter(\"four\")} |\n","pinned":false,"hidden":false,"mode":"md"},{"id":102,"value":"*band*.bandwidth indicates the band’s width. (To draw the actual rectangle, we have the position on the horizontal axis given as the return value of *four*, but we also need to know its width.) By definition for band scales, all bands have the same width:","pinned":false,"hidden":false,"mode":"md"},{"id":106,"value":"quarter.bandwidth()","pinned":true,"hidden":false,"mode":"ojs"},{"id":130,"value":"bars(quarter) // bars is a function defined in the Annex","pinned":true,"hidden":false,"mode":"ojs"},{"id":266,"value":"Once we have the general geometry of the bands, we can adjust the size of the gap between them, by setting [*band*.paddingInner](https://d3js.org/d3-scale/band#band_paddingInner) as _a proportion_, between 0 and 1. This value is a fraction of the “step”, which is the interval between the start of a band and the start of the next band:","pinned":false,"hidden":false,"mode":"md"},{"id":268,"value":"quarter.step()","pinned":true,"hidden":false,"mode":"ojs"},{"id":152,"value":"This a bit tricky if you want to follow the maths in your head, because the available range has to be divided between the *n* bands and the *n-1* gaps (inner paddings). The sum of the band widths and the gap width must still amount to the range. For example, for 50%:","pinned":false,"hidden":false,"mode":"md"},{"id":276,"value":"quarter50 = quarter.copy().paddingInner(0.6)","pinned":true,"hidden":false,"mode":"ojs"},{"id":136,"value":"bars(quarter50) // edit the padding value in [0,1] to see how the bands geometries change.","pinned":true,"hidden":false,"mode":"ojs"},{"id":279,"value":"quarter50.step() // should be equal to 2/(3+4) * width","pinned":true,"hidden":false,"mode":"ojs"},{"id":382,"value":"(If you need to set paddingInner to 1, so that the bandwidth is equal to 0, check [d3.scalePoint](https://observablehq.com/@d3/d3-scalepoint) instead.)","pinned":false,"hidden":false,"mode":"md"},{"id":180,"value":"[*band*.paddingOuter](https://d3js.org/d3-scale/band#band_paddingOuter) adjusts the padding on the outside, to leave some room for the axis or legend. In association with [*band*.align](https://observablehq.com/@d3/band-align) (also a value between [0,1]), you can control the padding on the left- and right-hand side of the scale:","pinned":false,"hidden":false,"mode":"md"},{"id":182,"value":"bars(\n quarter\n .copy()\n .paddingInner(0) // edit the inner padding value in [0,1]\n .paddingOuter(0.5) // edit the outer padding value in [0,1]\n .align(0.5) // edit the align: 0 is aligned left, 0.5 centered, 1 aligned right.\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":196,"value":"Lastly, [*band*.padding](https://d3js.org/d3-scale/band#band_padding) sets both paddingInner and paddingOuter to the same value. For the subtler details, see [this explainer on band.align](https://observablehq.com/@d3/band-align). Below you can explore how each element of configuration impacts the scale:","pinned":false,"hidden":false,"mode":"md"},{"id":397,"value":"scale = d3.scaleBand()\n .domain(\"ABCDEFGHIJKLMNOPQRSTUVWXYZ\".split(\"\").slice(0, domainCardinality))\n .range([40, 40 + rangeLength])\n .paddingInner(paddingInner)\n .paddingOuter(paddingOuter)\n .align(align)\n .round(enableRounding)","pinned":true,"hidden":false,"mode":"ojs"},{"id":565,"value":"viewof domainCardinality = (reset, Inputs.range([1, 7], {label: \"Domain #\", value: 3, step: 1}))","pinned":false,"hidden":false,"mode":"ojs"},{"id":563,"value":"viewof rangeLength = (reset, Inputs.range([100, width - 80], {label: \"Range\", value: Math.min(700, width - 80), step: 1}))","pinned":false,"hidden":false,"mode":"ojs"},{"id":561,"value":"viewof paddingInner = {\n reset;\n return Inputs.range([0, 1], {label: \"paddingInner\", value: 0.1, step: 0.01});\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":560,"value":"viewof paddingOuter = {\n reset;\n return Inputs.range([0, 1], {label: \"paddingOuter\", value: 0.2, step: 0.01})\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":559,"value":"viewof align = {\n reset;\n return Inputs.range([0, 1], {label: \"align\", value: 0.5, step: 0.01})\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":558,"value":"viewof enableRounding = {\n reset;\n return Inputs.toggle({label: \"Enable rounding\", value: true});\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":557,"value":"viewof reset = Inputs.button(\"Reset\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":402,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":492,"value":"_Note:_ left-pad will be computed as step × paddingOuter × align × 2, plus some ε if necessary when the scale is rounded! Substitute _align_ with _1 – align_ for the right-pad.","pinned":false,"hidden":false,"mode":"md"},{"id":204,"value":"[*band*.round](https://d3js.org/d3-scale/band#band_round) — and the shorthand notation [*band*.rangeRound](https://d3js.org/d3-scale/band#band_rangeRound) — give the results as integer values, using Math.floor() to avoid overflowing the range. This will usually leave some unused space, that must be allocated to the left and right padding (even if those have been set to 0). Align them with *band*.align.","pinned":false,"hidden":false,"mode":"md"},{"id":238,"value":"testround = d3.scaleBand()\n .domain([1, 2, 3, 4, 5, 6])\n .range([0, 100])\n .round(true) // 👀 change to false to see the impact below","pinned":true,"hidden":false,"mode":"ojs"},{"id":219,"value":"testround.bandwidth()","pinned":true,"hidden":false,"mode":"ojs"},{"id":260,"value":"testround.step()","pinned":true,"hidden":false,"mode":"ojs"},{"id":227,"value":"testround(1) // left pad + n * step = 100 - right pad","pinned":true,"hidden":false,"mode":"ojs"},{"id":531,"value":"Rounding is sometimes useful for avoiding antialiasing artifacts, though also consider the [shape-rendering](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/shape-rendering) “crispEdges” styles.","pinned":false,"hidden":false,"mode":"md"},{"id":298,"value":"As usual, *band*.round can also be used to read the setting:","pinned":false,"hidden":false,"mode":"md"},{"id":299,"value":"quarter.round()","pinned":true,"hidden":false,"mode":"ojs"},{"id":303,"value":"testround.round()","pinned":true,"hidden":false,"mode":"ojs"},{"id":307,"value":"[*band*.copy](https://github.com/d3/d3-scale/blob/master/README.md#band_copy) creates a copy of the band scale with the same settings. We’ve used it above to create variants of existing scales without mutating them.","pinned":false,"hidden":false,"mode":"md"},{"id":23,"value":"*unknown*. Contrary to [ordinal scales](https://observablehq.com/@d3/d3-scaleordinal?collection=@d3/d3-scale), a band scale’s domain must be defined in full beforehand, and cannot be constructed iteratively. By way of consequence, band scales have no *unknown* method: the result for any value outside the domain is undefined.","pinned":false,"hidden":false,"mode":"md"},{"id":98,"value":"quarter(\"nine\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":100,"value":"quarter(1.5)","pinned":true,"hidden":false,"mode":"ojs"},{"id":390,"value":"## Small multiple charts\n\nBand scales are often used to arrange small multiple charts, [horizontally](https://observablehq.com/@fil/summer-heat), vertically, or both.","pinned":false,"hidden":false,"mode":"md"},{"id":311,"value":"## Band scale domain\n\nA final note about band scales’ domains. As indicated in the API documentation:\n> _Domain values are stored internally in a map from stringified value to index; the resulting index is then used to determine the band. Thus, a band scale’s values must be coercible to a string, and the stringified version of the domain value uniquely identifies the corresponding band._","pinned":false,"hidden":false,"mode":"md"},{"id":313,"value":"naiveObjectBand = d3.scaleBand()\n .domain([{ name: \"Bob\" }, { name: \"Susie\" }, { name: \"Alice\" }])\n .rangeRound([0, 100])","pinned":true,"hidden":false,"mode":"ojs"},{"id":355,"value":"susie = ({ name: \"Susie\" })","pinned":true,"hidden":false,"mode":"ojs"},{"id":316,"value":"// 🌶 this gives an unexpected value, because every object was coerced to the same string \"[object Object]\"\nnaiveObjectBand(susie)","pinned":true,"hidden":false,"mode":"ojs"},{"id":345,"value":"This situation can be avoided by using an id:","pinned":false,"hidden":false,"mode":"md"},{"id":351,"value":"idObjectBand = d3.scaleBand()\n .domain(\n [{ name: \"Bob\" }, { name: \"Susie\" }, { name: \"Alice\" }].map(d => d.name)\n )\n .rangeRound([0, 100])","pinned":true,"hidden":false,"mode":"ojs"},{"id":353,"value":"idObjectBand(susie.name)","pinned":true,"hidden":false,"mode":"ojs"},{"id":39,"value":"---\n\n## Appendix\n\nThanks to [Jean-Daniel Browne](/@jdb), [Martin Stålberg](/@mast4461) and [Stephanie Tuerk](/@stephanietuerk) for their suggestions and clarifications.","pinned":false,"hidden":false,"mode":"md"},{"id":112,"value":"function bars(scale) {\n const margin = 10,\n width = 100,\n height = 60,\n chart = svg``;\n\n return chart;\n}","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}