30:[{"id":"31ca24545a0603dce099d10ee89ee5ae72d29fa55e8fc7c9ffb5ded87ac83060d80f1d9e21f4ae8eb04c1e8940b7287d179fe8060d887fb1f055f430e210007c","href":"https://static.observableusercontent.com/files/31ca24545a0603dce099d10ee89ee5ae72d29fa55e8fc7c9ffb5ded87ac83060d80f1d9e21f4ae8eb04c1e8940b7287d179fe8060d887fb1f055f430e210007c","name":"athletes.csv","type":"text/csv","lastModified":1638870464955.444,"size":841836},{"id":"831732e8332e141e39aca2776edfdb19b2d43308d4974f5ad4a21fad007faa0518fe5bc4a0fc4f57422689a161dc27b82073403cee0e29ebf6ccb75d0ec4aeb3","href":"https://static.observableusercontent.com/files/831732e8332e141e39aca2776edfdb19b2d43308d4974f5ad4a21fad007faa0518fe5bc4a0fc4f57422689a161dc27b82073403cee0e29ebf6ccb75d0ec4aeb3","name":"seattle-weather.csv","type":"text/csv","lastModified":1638956642903.668,"size":48219}] 2e:{"title":"Legends / Observable Plot","cells":[{"id":0,"value":"

Legends / Observable Plot

Observable Plot › Legends · API

\n\n# Plot: Legends\n\nAxes and legends are a key component of any chart: they help the reader to understand how the abstract dimensions of the data have been encoded as visual variables, and allow them to interpret the value of a given mark.","pinned":false,"hidden":false,"mode":"md"},{"id":943,"value":"Plot will generate a legend for a **color** or **opacity** scale with the addition of the *legend* option to the corresponding scale’s definition. For instance, the scatterplot below shows the height and weight of athletes in the Rio Olympics (data sourced from [Matt Riggott](https://flother.is/2017/olympic-games-data/)); sex is encoded as color.","pinned":false,"hidden":false,"mode":"md"},{"id":902,"value":"Plot.plot({\n color: {\n legend: true\n },\n marks: [\n Plot.dot(athletes, {x: \"weight\", y: \"height\", stroke: \"sex\"})\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":41,"value":"athletes = (await FileAttachment(\"athletes.csv\").csv({typed: true}))\n .filter(d => [\"aquatics\", \"volleyball\", \"football\", \"rowing\"].includes(d.sport))","pinned":true,"hidden":false,"mode":"ojs"},{"id":1189,"value":"Here’s another example with faceting…","pinned":false,"hidden":false,"mode":"md"},{"id":137,"value":"Plot.plot({\n grid: true,\n height: 320,\n color: {\n type: \"ordinal\",\n scheme: \"category10\",\n legend: true\n },\n facet: {\n data: athletes,\n x: \"sex\"\n },\n marks: [\n Plot.frame(),\n Plot.dot(athletes, {x: \"weight\", y: \"height\", fill: \"sport\", r: 1.5})\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":175,"value":"If the scale is ordinal or categorical, by default the legend appears as a list of swatches labeled with the names of the categories, as shown above. If the color scale is continuous, the legend switches to a horizontal ramp. Below, each athlete is represented by a dot positioned by height and date of birth, and colored by weight.","pinned":false,"hidden":false,"mode":"md"},{"id":159,"value":"faceted = Plot.plot({\n grid: true,\n height: 320,\n x: {\n nice: true\n },\n color: {\n scheme: \"warm\",\n nice: true,\n legend: true\n },\n facet: {\n data: athletes,\n x: \"sport\",\n y: \"sex\"\n },\n marks: [\n Plot.frame(),\n Plot.dot(athletes, {x: \"date_of_birth\", y: \"height\", fill: \"weight\", r: 1.5})\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":184,"value":"Note that, for ordinal scales, you can opt-out of swatches by specifying a *ramp* legend. (While technically possible, the converse—to render a continuous scale as a set of swatches—is not useful in general, except maybe for threshold scales.)","pinned":false,"hidden":false,"mode":"md"},{"id":157,"value":"sportsPlot = Plot.plot({\n color: {\n type: \"ordinal\",\n scheme: \"category10\",\n legend: \"ramp\"\n },\n marks: [\n Plot.dot(athletes, {x: \"weight\", y: \"height\", fill: \"sport\", stroke: \"white\"})\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":209,"value":"With the *legend* scale option, the legend is rendered together with the chart, wrapped in a figure element. An alternative, in particular when the same color scale is used across several charts, is to display the legend as a standalone element in a separate cell. For this, you can call *plot*.legend.","pinned":false,"hidden":false,"mode":"md"},{"id":112,"value":"sportsPlot.legend(\"color\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":237,"value":"*plot*.legend takes two arguments. The first is the name of the scale for which we want the legend (only *color* and *opacity* are supported for now); the second is an optional options object, which allows to customize the legend’s appearance.","pinned":false,"hidden":false,"mode":"md"},{"id":225,"value":"faceted.legend(\"color\", {label: \"Weight (kg) →\", ticks: 10, width: 350})","pinned":true,"hidden":false,"mode":"ojs"},{"id":243,"value":"Before we dive in the legend options, note that a Plot.*legend* function also exists, which takes a scale descriptor and legend options, and returns a legend independent of any chart. This can be useful to test scales, such as this function which maps a wave length (in nanometers) to a RGB color:","pinned":false,"hidden":false,"mode":"md"},{"id":299,"value":"Plot.legend({\n color: {\n interpolate: (t) => wavelengthToColor(400 + t * 350),\n domain: [400, 750]\n },\n width: 350,\n ticks: 10,\n label: \"Wavelength (nm) →\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":526,"value":"And, since *plot*.scale(*name*) returns a scale descriptor, you can likewise pass the result to Plot.legend.","pinned":false,"hidden":false,"mode":"md"},{"id":1205,"value":"Plot.legend({color: sportsPlot.scale(\"color\")})","pinned":true,"hidden":false,"mode":"ojs"},{"id":352,"value":"### Swatches options\n\nSwatches are generated in HTML, with the following options:","pinned":false,"hidden":false,"mode":"md"},{"id":999,"value":"viewof s = Inputs.form({\n columns: Inputs.select(\n new Map([\n [\"\", null],\n [\"2\", 2],\n [\"5\", 5],\n [\"10\", 10],\n [\"110px\", \"110px\"],\n [\"60px\", \"60px\"]\n ]),\n {label: \"columns\", value: \"110px\"}\n ),\n tickFormat: Inputs.select(\n new Map([\n [\"\", (d) => d],\n [\"d => d.slice(0,3)\", (d) => d.slice(0, 3)],\n [\"d => d.toUpperCase()\", (d) => d.toUpperCase()],\n [\"null\", null]\n ]),\n {\n label: \"tickFormat\"\n }\n ),\n swatchSize: Inputs.range([0, 40], {\n label: \"swatchSize\",\n step: 1,\n value: 15\n }),\n swatchWidth: Inputs.range([0, 40], {\n label: \"swatchWidth\",\n step: 1,\n value: 0\n }),\n swatchHeight: Inputs.range([0, 40], {\n label: \"swatchHeight\",\n step: 1,\n value: 0\n }),\n marginLeft: Inputs.range([0, 200], {\n label: \"marginLeft\",\n step: 1,\n value: 0\n }),\n width: Inputs.range([300, width], { label: \"width\", step: 1 })\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":393,"value":"Plot.legend({\n color: {\n domain: [\"Lagos\", \"Kano\", \"Ibadan\", \"Benin City\", \"Port Harcourt\", \"Jos\", \"Ilorin\", \"Abuja\", \"Kaduna\", \"Enugu\", \"Zaria\", \"Warri\", \"Ikorodu\", \"Maiduguri\", \"Aba\", \"Ife\", \"Bauchi\", \"Akure\", \"Abeokuta\", \"Oyo\"],\n scheme: \"turbo\"\n },\n legend: \"swatches\",\n columns: s.columns,\n width: s.width,\n tickFormat: s.tickFormat,\n swatchSize: s.swatchSize,\n swatchWidth: s.swatchWidth || undefined, // defaults to swatchSize\n swatchHeight: s.swatchHeight || undefined, // defaults to swatchSize\n marginLeft: s.marginLeft,\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":465,"value":"On top of the interactive options shown above, you can pass a *className* option that will supersede the randomly-generated class name, and a *style* option (as a string or an object) that will be merged with the built-in default styles.","pinned":false,"hidden":false,"mode":"md"},{"id":470,"value":"alpha = Plot.legend({\n color: {\n domain: \"ABCD\"\n },\n legend: \"swatches\",\n className: \"alphabet\",\n swatchSize: 20,\n style: {\n fontFamily: \"Comic Sans MS\",\n fontSize: \"20px\"\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":987,"value":"Note: the [columns](https://developer.mozilla.org/en-US/docs/Web/CSS/columns) option is a short-hand notation for columns-count (if specified as a number), and columns-width (if specified as a dimension, *e.g.* \"110px\"), allowing various kinds of responsive behaviors.","pinned":false,"hidden":false,"mode":"md"},{"id":358,"value":"### Ramp options\n\nRamps are generated in SVG, with the colors rendered on an embedded canvas. In what follows we’ll use the maximal daily temperature in Seattle over the course of a year as our dataset, and start from the visualisation developed in the [Plot: Cell](/@observablehq/plot-cell?collection=@observablehq/plot) notebook:","pinned":false,"hidden":false,"mode":"md"},{"id":568,"value":"seattle = FileAttachment(\"seattle-weather.csv\").csv({typed: true})","pinned":true,"hidden":false,"mode":"ojs"},{"id":577,"value":"tempChart = Plot.plot({\n height: 300,\n padding: 0,\n y: {\n tickFormat: Plot.formatMonth(\"en\", \"short\")\n },\n color: {\n type: \"diverging\",\n pivot: d3.mean(seattle, d => d.temp_max),\n reverse: true,\n legend: true\n },\n marks: [\n Plot.cell(seattle, Plot.group({fill: \"max\"}, {\n x: d => d.date.getUTCDate(),\n y: d => d.date.getUTCMonth(),\n fill: \"temp_max\",\n inset: 0.5\n }))\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":640,"value":"The scale’s label can be set explicitly with the *label* option:","pinned":false,"hidden":false,"mode":"md"},{"id":595,"value":"tempChart.legend(\"color\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":607,"value":"tempChart.legend(\"color\", {label: \"temperature (°C) →\"})","pinned":true,"hidden":false,"mode":"ojs"},{"id":649,"value":"Here’s an interactive playground showing some of the options of the ramp legend:","pinned":false,"hidden":false,"mode":"md"},{"id":727,"value":"viewof r = Inputs.form({\n tickSize: Inputs.range([0, 12], { label: \"tickSize\", step: 0.5, value: 6 }),\n ticks: Inputs.select(\n new Map([\n [\"—\", null],\n [\"number: 4\", 4],\n [\"number: 20\", 20],\n [\"[array]\", [1, 6, 11, 16, 21, 26, 31]]\n ]),\n {\n label: \"ticks\",\n value: null\n }\n ),\n tickFormat: Inputs.select(\n new Map([\n [\"\", (d) => d],\n [\".1f\", \".1f\"],\n [\"function: (d) => `${d}°C`\", (d) => `${d}°C`],\n //[\"null\", null],\n ]),\n {\n label: \"tickFormat\"\n }\n ),\n width: Inputs.range([300, width], { label: \"width\", step: 1 }),\n height: Inputs.range([20, 68], { label: \"height\", step: 1, value: 44 }),\n round: Inputs.toggle({ label: \"round\" })\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":658,"value":"tempChart.legend(\"color\", {\n label: \"temperature (°C) →\",\n tickSize: r.tickSize,\n ticks: r.ticks,\n tickFormat: r.tickFormat,\n round: r.round,\n width: r.width,\n height: r.height + r.tickSize\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":719,"value":"Notes:\n- The default *height* is 44 pixels + the tickSize.\n- The *round* option positions the ticks on integer pixel positions.\n- The *marginTop*, *marginRight*, *marginBottom* and *marginLeft* options allow to adjust the margins.\n- As with the swatches legend, the *className* and *style* options allow to modify the default (randomly-generated) class name and add to the default styles.","pinned":false,"hidden":false,"mode":"md"},{"id":362,"value":"### Opacity\n\nThe legend for opacity scales is a *ramp* going from white (transparent) to black (fully opaque). It has the same options as the ramp legend, with an added *color* option setting the opaque color:","pinned":false,"hidden":false,"mode":"md"},{"id":548,"value":"Plot.legend({opacity: {domain: [0, 10]}})","pinned":true,"hidden":false,"mode":"ojs"},{"id":552,"value":"Plot.legend({opacity: {type: \"linear\"}, color: \"orange\"})","pinned":true,"hidden":false,"mode":"ojs"},{"id":18,"value":"Next \nAPI Reference","pinned":false,"hidden":false,"mode":"md"},{"id":1132,"value":"---\n## Appendix\n\nPlot [scales](/plot-scales?collection=@observablehq/plot) encode abstract data as visual variables such as position or color. You can access the scale description for any generated plot by calling *plot*.scale(*name*). The returned scale object includes the scale’s *domain* (abstract input) and *range* (visual output), and thus can be used to create a custom legend. For example, here’s the color scale definition one of the a scatterplots above.:","pinned":false,"hidden":false,"mode":"md"},{"id":1135,"value":"sportsScale = sportsPlot.scale(\"color\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":1134,"value":"And here’s using it to build a custom legend:","pinned":false,"hidden":false,"mode":"md"},{"id":1136,"value":"

${sportsScale.domain.map((sport) => htl.html`

${sport.toUpperCase()}

`)}

","pinned":true,"hidden":false,"mode":"html"},{"id":1234,"value":"Lastly, here’s a function to convert a wavelength in nanometers to an RGB color, used in an example above and adapted from [scienceprimer.com](https://scienceprimer.com/javascript-code-convert-light-wavelength-color).","pinned":false,"hidden":false,"mode":"md"},{"id":292,"value":"function wavelengthToColor(wl) {\n let R, G, B, alpha;\n\n if (wl >= 380 && wl < 440) {\n R = (-1 * (wl - 440)) / (440 - 380);\n G = 0;\n B = 1;\n } else if (wl >= 440 && wl < 490) {\n R = 0;\n G = (wl - 440) / (490 - 440);\n B = 1;\n } else if (wl >= 490 && wl < 510) {\n R = 0;\n G = 1;\n B = (-1 * (wl - 510)) / (510 - 490);\n } else if (wl >= 510 && wl < 580) {\n R = (wl - 510) / (580 - 510);\n G = 1;\n B = 0;\n } else if (wl >= 580 && wl < 645) {\n R = 1;\n G = (-1 * (wl - 645)) / (645 - 580);\n B = 0.0;\n } else if (wl >= 645 && wl <= 780) {\n R = 1;\n G = 0;\n B = 0;\n } else {\n R = 0;\n G = 0;\n B = 0;\n }\n\n // intensity is lower at the edges of the visible spectrum.\n if (wl > 780 || wl < 380) {\n alpha = 0;\n } else if (wl > 700) {\n alpha = (780 - wl) / (780 - 700);\n } else if (wl < 420) {\n alpha = (wl - 380) / (420 - 380);\n } else {\n alpha = 1;\n }\n\n return `rgb(${R * alpha * 100}%,${G * alpha * 100}%,${B * alpha * 100}%)`;\n}","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W30","stdlib":"1","titling":"auto"}