30:T48b,function draw_buckets(bin, values) { const svg = this || DOM.svg(width, 100); const buckets = bin(values); const binColor = d3 .scaleThreshold() .domain(buckets.map(d => d.x0)) .range(colors); d3.select(svg) .selectAll("rect") .data(buckets) .join("rect") .attr("y", d => 10) .attr("height", 100 - 2 * 10) .attr("x", d => (x(d.x0) + 1) | 0) .attr("width", d => (x(d.x1) | 0) - (x(d.x0) | 0) - 2) .attr("stroke", d => binColor(d.x0)) .attr("stroke-width", 1) .attr("stroke-dasharray", d => (d.length === 0 ? "1 5" : null)) .attr("fill", "none"); draw_values(svg, values); d3.select(svg) .selectAll("circle") .attr("fill", binColor) .attr("stroke", binColor); d3.select(svg) .selectAll("text") .data(buckets.filter(d => d.length > 0)) .join("text") .attr("x", d => (x(d.x0) + 3) | 0) .attr("y", 86) .attr("fill", "black") .attr("font-size", 9) .text(d => x(d.x1) - x(d.x0) < 50 ? d.length : d.length > 1 ? `${d.length} items` : d.length === 1 ? "1 item" : "empty bin" ); return svg; }31:T994,function draw_histogram_from_buckets(buckets, x, opts = {}) { const width = opts.width || 300, height = opts.height || 200, margin = opts.margin || { top: 20, right: 20, bottom: 30, left: 40 }, svg = d3.select(DOM.svg(width, height)), maxBins = d3.max(buckets, d => d.length), data = buckets.flat(), count = data.length, y = d3 .scaleLinear() .domain([0, maxBins]) .nice() .range([height - margin.bottom, margin.top]), frequency = opts.relative ? d3 .scaleLinear() .domain([0, maxBins / count]) .nice() .range([height - margin.bottom, margin.top]) : y, xAxis = g => g .attr("transform", `translate(0,${height - margin.bottom})`) .call(d3.axisBottom(x).tickSizeOuter(0)) .call(g => g .append("text") .attr("x", width - margin.right) .attr("y", -4) .attr("fill", "#000") .attr("font-weight", "bold") .attr("text-anchor", "end") .text(opts.xText) ); const binColor = d3 .scaleThreshold() .domain(buckets.map(d => d.x0)) .range(colors); svg .append("g") .selectAll("rect") .data(buckets) .join("rect") .attr("fill", opts.fill || (d => binColor(d.x0))) .attr("x", d => x(d.x0) + 1) .attr("width", d => Math.max(0, x(d.x1) - x(d.x0) - 1)) .attr("y", d => y(d.length)) .attr("height", d => y(0) - y(d.length)); svg.append("g").call(xAxis); if (opts.title) svg .append("g") .append("text") .text(opts.title) .style("fill", "#000") .attr("font-weight", "bold") .style("font-size", 14) .style("text-anchor", "end") .attr("x", width - 30) .attr("y", 10); const labels = svg .append("g") .selectAll("text") .data(buckets.filter(d => d.length > 0)) .join("text") .attr("x", d => ((x(d.x0) + x(d.x1)) / 2) | 0) .attr("y", d => y(d.length) - 2) .style("fill", "black") .style("font-size", 10) .style("text-anchor", "middle"); if (opts.relative) { const format = d3.format(".1%"); labels.text(d => format(d.length / count)); } else labels.text(d => x(d.x1) - x(d.x0) < 50 ? d.length : d.length > 1 ? `${d.length} items` : d.length === 1 ? "1 item" : "empty bucket" ); return svg.node(); }32:[] 2e:{"title":"d3.bin","cells":[{"id":0,"value":"# d3.bin\n\n[d3.bin](https://d3js.org/d3-array/bin#bin) groups data points into buckets of (usually) equal widths along a comparison axis.\n\nThese buckets can be represented by a [histogram](/@d3/histogram) (*a.k.a.* a frequency bar chart), that shows buckets as a bar with a length proportional to the number of elements of each bucket.","pinned":false,"hidden":false,"mode":"md"},{"id":736,"value":"For starters, suppose we want to study a distribution of ${\n values1.length\n} random values, positioned on the *x* axis and represented by small dots. (To limit the overlap on the screen, we’ll give the dots an arbitrary position on the *y* axis. Their position on *x* will follow various types of distributions defined in [d3-random](https://observablehq.com/@d3/d3-random).)","pinned":false,"hidden":false,"mode":"md"},{"id":1651,"value":"values1 = distribution(\"Uniform\") // 1000 values distributed with d3.randomUniform","pinned":true,"hidden":false,"mode":"ojs"},{"id":218,"value":"draw_values(this || DOM.svg(width, 100), values1)","pinned":false,"hidden":false,"mode":"ojs"},{"id":577,"value":"The data stucture computed by d3.bins is an array of arrays that represent buckets. Each of these buckets has two attributes: its lowest value *x0*, and its highest value *x1*. Each of the buckets contains the data points whose value *v* lies between the bucket’s *x0* and *x1* attributes.\n\nMore precisely:\n- *x0* ≤ *v* < *x1* for all but the last bucket, and\n- *x0* ≤ *v* ≤ *x1* for the last bucket. 🌶","pinned":false,"hidden":false,"mode":"md"},{"id":1817,"value":"Let’s start by defining a binning operator, with d3.bin:","pinned":false,"hidden":false,"mode":"md"},{"id":612,"value":"bin1 = d3.bin()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1073,"value":"Applying bin1 to the array *values1* returns this array of buckets:","pinned":false,"hidden":false,"mode":"md"},{"id":1075,"value":"buckets1 = bin1(values1)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1078,"value":"We can inspect this result visually, by drawing each bin as a rectangle enclosing the dots it contains. As we can see, all buckets have the same width; they do not necessarily contain the same number of elements:","pinned":false,"hidden":false,"mode":"md"},{"id":649,"value":"draw_buckets(bin1, values1)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1085,"value":"Histograms allow to quickly grasp the shape of a distribution. The bins returned by d3.bin are customarily represented by a _histogram chart_ (or _frequency bar chart_), in which each bar represents a bucket, and the height of each bar figures the number of elements it contains.","pinned":false,"hidden":false,"mode":"md"},{"id":1265,"value":"draw_histogram_from_buckets(buckets1, x, {\n width,\n yText: \"absolute frequency (#)\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1268,"value":"Since we’re playing with generated data, let’s try a different type of [random distribution](https://observablehq.com/@d3/d3-random), and compute new buckets:","pinned":false,"hidden":false,"mode":"md"},{"id":1288,"value":"Click on the buttons below to try various shapes:","pinned":false,"hidden":false,"mode":"md"},{"id":1222,"value":"viewof values2 = select_distribution(\"Normal\", \"Distribution for values2\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":1087,"value":"draw_buckets(bin2, values2)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1129,"value":"draw_histogram_from_buckets(buckets2, x, {\n width,\n yText: \"absolute frequency (#)\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1252,"value":"bin2 = d3.bin()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1246,"value":"buckets2 = bin2(values2)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1300,"value":"## Parameters","pinned":false,"hidden":false,"mode":"md"},{"id":740,"value":"d3.bin doesn’t generate the buckets directly: it returns a function that can be parametrized before it is applied to the data to generate the buckets.\n\nWith the default parameters, that function knows how to automatically adapt to the data: first it will look at the **value** of each data point; its **domain** will encompass the full extent of these values (from lowest to highest), slice it according to a certain number of equally-sized buckets separated by **thresholds**, and bin the data points into these buckets.","pinned":false,"hidden":false,"mode":"md"},{"id":708,"value":"We’ll now look in turn at how each of these terms impacts the binning:","pinned":false,"hidden":false,"mode":"md"},{"id":1391,"value":"[*bin*.value](https://d3js.org/d3-array/bin#bin_value) is an accessor function. To bin objects based on their property *p*, do:","pinned":false,"hidden":false,"mode":"md"},{"id":1041,"value":"{\n const values = Array.from({ length: 100 }, (d, i) => ({\n label: i,\n p: Math.random()\n })),\n bin = d3.bin().value(d => d.p);\n return bin(values);\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":638,"value":"[*bin*.domain](https://d3js.org/d3-array/bin#bin_domain) defines the lowest and highest value to be considered. For example, in a left skewed distribution, such as the one below, we might not care so much for the “long tail” of points with a value *v* > ${max3}. So we might be tempted to manually limit the domain to a more relevant interval [0,${max3}]:","pinned":false,"hidden":false,"mode":"md"},{"id":788,"value":"viewof max3 = Inputs.range([0,20], {\n value: 10,\n step: 1,\n label: \"Highest value\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":653,"value":"bin3 = d3.bin().domain([0, max3])","pinned":true,"hidden":false,"mode":"ojs"},{"id":1347,"value":"buckets3 = bin3(values3)","pinned":false,"hidden":false,"mode":"ojs"},{"id":651,"value":"draw_buckets(bin3, values3)","pinned":false,"hidden":false,"mode":"ojs"},{"id":659,"value":"{\n const lost = values3.length - d3.sum(bin3(values3), d => d.length),\n percent = (100 * lost) / values3.length;\n return md`_${lost} points outside the domain [${bin2\n .domain()(values3)[0]\n .toFixed(1)},${bin3\n .domain()(values3)[1]\n .toFixed(1)}] have been left out of the histogram.
${\n percent === 0\n ? \"\"\n : percent < 2\n ? `That can be an acceptable ${percent.toFixed(1)}%.`\n : percent < 8\n ? `Ignoring ${percent.toFixed(1)}% of outliers is up to you.`\n : `That’s **a whopping ${percent.toFixed(1)}%**!`\n }_`;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":959,"value":"However, once we manually set *bin*.domain, the bin does not adapt to the data anymore. Try a different distribution and see the mess! Then, change the domain with the slider, or in the definition of bin3, to fit the data.","pinned":false,"hidden":false,"mode":"md"},{"id":1642,"value":"viewof values3 = select_distribution(\"Skewed left\", \"Distribution for values3\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":854,"value":"If called with no argument, *bin*.domain will return the domain accessor, *i.e.* a function that compute the domain from the data. If, as we did here, we have manually fixed the bin’s domain to a certain segment [min,max], *bin*.domain will return that segment:","pinned":false,"hidden":false,"mode":"md"},{"id":859,"value":"bin3.domain()(values3)","pinned":true,"hidden":false,"mode":"ojs"},{"id":864,"value":"By default, the domain accessor will use the data’s extent, and ensures no data point will be lost:","pinned":false,"hidden":false,"mode":"md"},{"id":866,"value":"d3.bin().domain()(values3)","pinned":true,"hidden":false,"mode":"ojs"},{"id":873,"value":"A useful way to give a proper domain to a bin is to create a [scale](https://observablehq.com/collection/@d3/d3-scale) with *nice* bounds, and use that scale’s domain as input for the bin’s domain:","pinned":false,"hidden":false,"mode":"md"},{"id":875,"value":"bin4 = {\n const scale = d3\n .scaleLinear()\n .domain(d3.extent(values3))\n .nice(); // 😃\n return d3.bin().domain(scale.domain());\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":878,"value":"draw_buckets(bin4, values3)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1403,"value":"bin4.domain()()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1412,"value":"## Thresholds\n\n[*bin*.thresholds](https://d3js.org/d3-array/bin#bin_thresholds) sets (or reads) the thresholds. Note that this is not as straightforward as it seems: *bin*.thresholds accepts various types of arguments, depending on the strategy we want the bin to use when it will read the data.","pinned":false,"hidden":false,"mode":"md"},{"id":1440,"value":"In the most straightforward instance, we can pass an array of values and set the thresholds manually:","pinned":false,"hidden":false,"mode":"md"},{"id":1444,"value":"bin5 = d3.bin().thresholds([0, 2, 5, 10, 15])","pinned":true,"hidden":false,"mode":"ojs"},{"id":1416,"value":"draw_buckets(bin5, values3)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1044,"value":"Another way of specifying the thresholds settings is to pass a number, indicative of how many buckets we would like to create:","pinned":false,"hidden":false,"mode":"md"},{"id":1474,"value":"viewof nthresholds = Inputs.range([0, 50], {\n label: \"# of thresholds to aim for\",\n value: 20,\n step: 1\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1418,"value":"bin6 = d3.bin().thresholds(nthresholds)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1451,"value":"draw_buckets(bin6, values3)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1494,"value":"In this case, we indicated *bin*.thresholds(${nthresholds}) and received ${\n bin6(values3).length\n} buckets.","pinned":false,"hidden":false,"mode":"md"},{"id":1471,"value":"Unexpected? The result is _not_ guaranteed to yield the exact number of buckets we asked for. That number is only an indication, passed to the threshold generator. As you change that value with the slider, you might notice the reason why this happens: the domain gets sliced at “nicely-rounded” values — using [d3.ticks](https://observablehq.com/@d3/d3-ticks) — and these rounded values do not fall exactly on the bin’s domain.","pinned":false,"hidden":false,"mode":"md"},{"id":1496,"value":"Several thresholds generators are available with d3-array:","pinned":false,"hidden":false,"mode":"md"},{"id":1523,"value":"[d3.thresholdSturges](https://d3js.org/d3-array/bin#thresholdSturges) (used by default) is based on [Sturges’s formula](https://en.wikipedia.org/wiki/Histogram#Mathematical_definition) (1926). After reading the values, it returns a number that, in turn, will be passed to d3.ticks to compute the actual thresholds.","pinned":false,"hidden":false,"mode":"md"},{"id":1536,"value":"[d3.thresholdScott](https://d3js.org/d3-array/bin#thresholdScott) applies [Scott’s normal reference rule](https://en.wikipedia.org/wiki/Histogram#Scott's_normal_reference_rule).","pinned":false,"hidden":false,"mode":"md"},{"id":1529,"value":"[d3.thresholdFreedmanDiaconis](https://d3js.org/d3-array/bin#thresholdFreedmanDiaconis) applies [Freedman–Diaconis’ choice](https://en.wikipedia.org/wiki/Histogram#Freedman%E2%80%93Diaconis'_choice).","pinned":false,"hidden":false,"mode":"md"},{"id":1533,"value":"From Wikipedia:\n> _These three generators implicitely assume a normal distribution. Scott’s normal reference rule is optimal for random samples of normally distributed data. Freedman–Diaconis’ choice is less sensitive than the standard deviation to outliers in data._","pinned":false,"hidden":false,"mode":"md"},{"id":1547,"value":"Here’s a visualization of those three strategies, applied to the same data distribution:","pinned":false,"hidden":false,"mode":"md"},{"id":1564,"value":"viewof values4 = select_distribution(\"Skewed left\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":1549,"value":"draw_histogram_from_buckets(\n d3.bin().thresholds(d3.thresholdSturges)(values4),\n x,\n {\n width,\n title: \"Sturges’ formula\"\n }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1551,"value":"draw_histogram_from_buckets(\n d3.bin().thresholds(d3.thresholdScott)(values4),\n x,\n {\n width,\n title: \"Scott’s normal reference rule\"\n }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1556,"value":"draw_histogram_from_buckets(\n d3.bin().thresholds(d3.thresholdFreedmanDiaconis)(values4),\n x,\n {\n width,\n title: \"Friedman-Diaconis’ rule\"\n }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":912,"value":"**Defining your own threshold generator**. The threshold generator receives (values, min, max) as arguments. The threshold generators provided by d3-array work with numbers only — here’s an example that classifies words with respect to their initial letters.","pinned":false,"hidden":false,"mode":"md"},{"id":893,"value":"textbin = d3\n .bin()\n .thresholds((data, min, max) => [...new Set(data.map(d => d[0]))].sort())","pinned":true,"hidden":false,"mode":"ojs"},{"id":1918,"value":"textbin(\n `Après la faculté de penser, celle de communiquer ses pensées à ses semblables est l'attribut le plus frappant qui distingue l'homme de la brute`\n .toLowerCase()\n .split(/[\\s']/)\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":916,"value":"Another method could be to use some machine learning-fu to partition the dataset. With the help of simple-statistics, we can split the values in ${chunks} chunks using the [ckmeans](https://simple-statistics.github.io/docs/#ckmeans) algorithm, which will create as many buckets of data.","pinned":false,"hidden":false,"mode":"md"},{"id":918,"value":"simple = require(\"simple-statistics@7\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":945,"value":"viewof chunks = Inputs.range([2, 20], {\n value: 10,\n step: 1,\n label: \"# of chunks\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":923,"value":"bin25 = d3.bin()\n .thresholds(data => simple.ckmeans(data, chunks).map(l => d3.min(l)))","pinned":true,"hidden":false,"mode":"ojs"},{"id":927,"value":"draw_buckets(bin25, values5)","pinned":false,"hidden":false,"mode":"ojs"},{"id":938,"value":"viewof values5 = select_distribution(\"Normal\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":1097,"value":"Another possibility is to partition the domain into ${chunks} segments of equal lengths (without using the “nice” rounding pertaining to d3.ticks):","pinned":false,"hidden":false,"mode":"md"},{"id":975,"value":"bin26 = d3.bin()\n .thresholds((data, min, max) =>\n d3.range(chunks).map(t => min + (t / chunks) * (max - min))\n )","pinned":true,"hidden":false,"mode":"ojs"},{"id":978,"value":"draw_buckets(bin26, values5)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1856,"value":"Finally, if you need to partition 2-dimensional data using a similar logic, have a look at [d3-hexbin](https://observablehq.com/collection/@d3/d3-hexbin).","pinned":false,"hidden":false,"mode":"md"},{"id":6,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":271,"value":"max = 18","pinned":true,"hidden":false,"mode":"ojs"},{"id":230,"value":"x = d3.scaleLinear()\n .domain([0, max])\n .range([30, width - 30])\n .clamp(false)","pinned":true,"hidden":false,"mode":"ojs"},{"id":480,"value":"$30","pinned":true,"hidden":false,"mode":"ojs"},{"id":166,"value":"function draw_values(svg, values) {\n // We sort the data for meaningful transitions.\n const current = values.slice().sort();\n\n const prev = (svg && svg.values) || current;\n\n svg.values = current;\n\n d3.select(svg)\n .selectAll(\"circle\")\n .data(current)\n .join(\"circle\")\n .attr(\"r\", 2)\n .attr(\"stroke\", \"#588\")\n .attr(\"fill\", \"lightblue\")\n .attr(\"fill-opacity\", 0.3)\n .attr(\"cx\", (_, i) => x(prev[i]))\n .attr(\"cy\", (_, i) => y(i))\n .transition()\n .duration(500)\n .attr(\"cx\", x);\n\n return svg;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1517,"value":"colors = [\"black\"]\n .concat(d3.schemeCategory10)\n .concat(d3.schemePaired)\n .concat(d3.schemePastel1)\n .concat(d3.schemePastel2)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1184,"value":"$31","pinned":true,"hidden":false,"mode":"ojs"},{"id":801,"value":"y = {\n const frac = x => x - (x | 0);\n return i => 50 + 25 * frac(952 * Math.sin((i + 0.5) * 876));\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":155,"value":"randomDistributions = {\n const r20 = d3.randomNormal(max * 0.3, 2),\n r21 = d3.randomNormal(max * 0.75, 1),\n r4 = d3.randomExponential(0.3);\n return [\n { label: \"Uniform\", random: d3.randomUniform(0.5, max - 0.3) },\n { label: \"Normal\", random: d3.randomNormal(max / 2, (1.4 * max) / 18) },\n { label: \"Two blobs\", random: () => (Math.random() > 0.3 ? r20() : r21()) },\n { label: \"Skewed right\", random: d3.randomLogNormal() },\n { label: \"Skewed left\", random: () => 18 - r4() }\n ];\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1871,"value":"function distribution(label) {\n return select_distribution(label).value\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1635,"value":"function select_distribution(\n label,\n description = \"Random distribution\",\n length = 1000\n) {\n const form = html``;\n form.oninput = () => {\n form.value = Float32Array.from(\n { length },\n randomDistributions[+form.radio.value].random\n );\n };\n form.onchange = () => {\n // Safari…\n form.value = form.radio.value;\n form.dispatchEvent(new CustomEvent(\"input\"));\n };\n form.oninput();\n return form;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1952,"value":"---\nThanks to [John Alexis Guerra Gómez](/@john-guerra) and [Paul Murray](/@plmrry) for suggestions.","pinned":false,"hidden":false,"mode":"md"}],"files":"$W32","stdlib":"1","titling":"auto"}