2f:T975,# Plot extensibility ([#1836](https://github.com/observablehq/plot/pull/1836)) ## Obsolete copy. See the PR. --- Observable Plot is highly configurable, with a myriad of options — often represented as simple strings — to cover many common use cases in the most concise way. These options encode standard and well-tested methods, with the goal of helping anyone go from zero to chart as quickly as possible. However, there are times when you’ll want to go beyond these built-in behaviors and create unique features. To support creative and ad hoc, Plot is also highly extensible. Most of its options can be specified freely by writing JavaScript. You can think of this as an escape hatch for when none of the pre-programmed choices seems to be working for your use case. You can also picture this as creating space for experimentation and development of advanced techniques, or as a general mechanism to “hack and customize” Plot, for example to create new mark types or plugins. It is also, for example, a way to make use of [extended map projections](https://github.com/d3/d3-geo-projection) which we wouldn’t want to bundle in with Plot. The API for each of these options is tailored to what it needs to achieve. It is minimal, in the sense that the JavaScript code you write is only invoked with the data it is supposed to work with. For example, a custom reducer only receives its input values (_e.g._ a window into a series in a facet). This ensures that your code can focus on its purpose and be fast, and also that it will not have to be modified when new features are added. If you’d like to use this escape hatch for a use case that might be useful to more people, please open a [feature request](https://github.com/observablehq/plot/issues) describing what you’re trying to achieve. Someone in the community might also need this — or might already have built it! Plot comes with typescript declarations that document the inputs and expected outputs of these options, and many implementation examples. When in doubt, please open a [GitHub discussion](https://github.com/observablehq/plot/discussions) or post a question [in the Observable forum](https://talk.observablehq.com/). Here is an overview of the many places where writing custom JavaScript code allows you to go beyond the presets. We have annotated each of the sections with spices indicating their relative difficulty level.30:T5be,## Custom marks 🌶🌶🌶 Marks are class objects with various methods that Plot calls in sequence to: 1. _construct_ the mark: define its constant options and its channels. 2. _initialize_ (apply the transforms and gather the channels) 3. re-initialize with the scales, if an initializer is present in the options 4. _scale_ the values, _project_ the points if a projection is present 5. _filter_ out invalid values 6. _render_ a svg fragment to append to the current facet Each of these steps can be modified in JavaScript by extending the default [Mark](https://github.com/observablehq/plot/blob/main/src/mark.js) class. (You can also choose to extend any of the built-in mark classes — for example Text if the mark you want to create is similar to a text mark.) A custom mark can be as simple as changing a default option, for example the [hexagon](https://observablehq.com/plot/marks/dot#hexagon) mark only [sets](https://github.com/observablehq/plot/blob/8b9016a5da5b3e26c5ab0ebf934553e8e20f0d03/src/marks/dot.js#L150) the **symbol** option to “hexagon”. On the other end of the spectrum, a mark can overload all the methods. The example below shows how the mark’s filter method works, by presenting a custom mark (Dot2) which does not render circles whose _scaled_ radius is less than 3 pixels. (Note that this is different from the [filter transform](https://observablehq.com/plot/transforms/filter#filter-transform) which operates in data space.)31:T42c,### Render transforms 🌶🌶🌶 Render transforms take over the last stage of the process: rendering the processed data to the screen. This power can be used modestly, for example to tweak the usual representation by adding a fade-in effect. You can also totally replace the usual render method with a different technique — for example to render to a canvas image appended to a [foreignObject](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/foreignObject), if you need to draw hundred of thousands of dots. This is where you can plug custom interactive behaviors (for pointing, brushing…, possibly using D3), or the [SVG animation API](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/animate), or even asynchronous functions for delayed rendering. The [marks feature](https://observablehq.com/plot/features/marks) page goes through the complete API, and details a few examples. Render transforms are so powerful that it is tempting to use them as a go-to _hook_ to modify a mark; keep in mind however that it is not always the best approach!32:T743,oleron = d3.piecewise(Array.from("#192659#1b275b#1d295c#1e2a5e#202c5f#212d61#232f62#243064#263265#273367#293568#2a376a#2c386b#2d3a6d#2f3b6f#303d70#323e72#344073#354275#374376#384578#3a467a#3b487b#3d4a7d#3f4b7e#404d80#424e82#445083#455285#475387#485588#4a578a#4c588c#4d5a8d#4f5c8f#515d91#525f92#546194#566296#586497#596699#5b689b#5d699d#5e6b9e#606da0#626ea2#6470a3#6572a5#6774a7#6975a9#6b77aa#6c79ac#6e7bae#707cb0#727eb2#7380b3#7582b5#7784b7#7985b9#7a87ba#7c89bc#7e8bbe#808dc0#828ec2#8390c3#8592c5#8794c7#8996c9#8b97cb#8d99cd#8e9bce#909dd0#929fd2#94a1d4#96a3d6#98a4d7#99a6d9#9ba8db#9daadd#9facde#a1aee0#a3afe2#a5b1e4#a6b3e5#a8b5e7#aab7e8#acb9ea#aebaeb#afbcec#b1beed#b3bfee#b4c1f0#b6c3f0#b8c4f1#b9c6f2#bbc7f3#bcc9f4#becaf4#bfccf5#c0cdf5#c2cff6#c3d0f6#c5d1f7#c6d3f7#c7d4f8#c9d5f8#cad7f8#cbd8f9#cdd9f9#cedbf9#cfdcfa#d1ddfa#d2dffb#d3e0fb#d5e1fb#d6e3fc#d7e4fc#d9e5fc#dae7fd#dbe8fd#dde9fd#deebfe#dfecfe#e1edfe#e2efff#e3f0ff#e5f1ff#e6f3ff#194c00#1c4d00#1f4e00#224e00#244f00#275000#295100#2c5100#2e5200#315300#335300#355400#375500#395500#3c5600#3e5700#405700#425800#445900#465900#485a00#4a5b00#4d5b01#4f5c01#515d01#535e02#555f03#575f03#5a6004#5c6105#5e6207#606308#63640a#65650c#67670e#6a6810#6c6912#6e6a14#716c16#736d18#756e1a#78701c#7a711e#7c7221#7e7423#817525#837627#85782a#87792c#8a7b2e#8c7c30#8e7d33#907f35#928037#948239#97833c#99843e#9b8640#9d8742#9f8945#a18a47#a48c49#a68d4c#a88f4e#aa9050#ac9252#af9455#b19557#b39759#b5985c#b89a5e#ba9c60#bc9e62#bf9f65#c1a167#c3a369#c5a56c#c8a66e#caa871#ccaa73#cfac75#d1ae78#d3af7a#d5b17c#d8b37f#dab581#dcb784#deb986#e0ba89#e2bc8b#e4be8e#e6c090#e8c293#e9c495#ebc698#ecc89a#eec99d#efcb9f#f0cda2#f1cfa4#f2d1a7#f3d2a9#f4d4ac#f4d6ae#f5d7b0#f6d9b3#f6dbb5#f7dcb7#f7deba#f7e0bc#f8e1be#f8e3c0#f9e4c3#f9e6c5#f9e8c7#f9e9ca#faebcc#faecce#faeed1#fbf0d3#fbf1d5#fbf3d8#fcf5da#fcf6dc#fcf8df#fdfae1#fdfbe4#fdfde6".matchAll(/#\w+/g), ([d]) => d))33:T516,## Custom spatial interpolators 🌶🌶 [Spatial interpolators](https://observablehq.com/plot/marks/raster#spatial-interpolators) power the raster and contour marks. They attribute a value to every pixel on a grid, based on an array of samples that have x and y coordinates and a value. The built-in interpolators allow to evaluate a pixel based on the nearest neighbor, or through a random walk that returns the first match, for example. However these built-ins are far from covering the whole extent of spatial interpolators that exist in the scientific literature. Programming a custom interpolator can be a fun challenge. Once you do it, it will be available to derive contours and rasters alike, across the diverse landscape of Plot use-cases (including map projections, faceting, etc.). The only thing you need to care about is to fill the output, which is an array representing a grid of pixels. In the following example, we’ll color each pixel by its distance to the closest sample, up to 15 pixels. To make the look-ups fast enough, we’ll first build a spatial index (with [d3-quadtree](https://d3js.org/d3-quadtree); note however that with a bit of optimization, [delaunay.find](https://d3js.org/d3-delaunay/delaunay#delaunay_find) is faster when, like here, we compute _every_ pixel).34:[{"id":"7c6167b65013c12f3978b4d8e85dd28a27e3b5eb580d1e76696ce5b0d399c196de2b02c45e734462931e1af823698e36bb072722253d5e03e7fb61222755bc0c","href":"https://static.observableusercontent.com/files/7c6167b65013c12f3978b4d8e85dd28a27e3b5eb580d1e76696ce5b0d399c196de2b02c45e734462931e1af823698e36bb072722253d5e03e7fb61222755bc0c","name":"countries-110m.json","type":"application/json","lastModified":1692295633405.712,"size":107761},{"id":"b78f8bcd4b540922c6c36bbf0c3dac9109bcf248ccaeb4e26d573e5b236ee39bb47a553d352e9255ed2cd0d01bccf35b142536c1b1e963040a31000ea619b875","href":"https://static.observableusercontent.com/files/b78f8bcd4b540922c6c36bbf0c3dac9109bcf248ccaeb4e26d573e5b236ee39bb47a553d352e9255ed2cd0d01bccf35b142536c1b1e963040a31000ea619b875","name":"sf-temperatures.csv","type":"text/csv","lastModified":1692295633405.712,"size":15106}] 2d:{"title":"Plot extensibility (#1836)","cells":[{"id":25,"value":"$2f","pinned":false,"hidden":false,"mode":"md"},{"id":145,"value":"toc()","pinned":true,"hidden":false,"mode":"ojs"},{"id":118,"value":"## Channel value functions 🤞\n\nA [channel](https://observablehq.com/plot/features/marks#marks-have-channels) can be specified as an **accessor function**. For example, this [candlestick chart](https://observablehq.com/@observablehq/plot-candlestick-chart) draws a vertical link between the opening and closing values of a stock ticker with a color showing whether the value has increased or decreased:\n\n~~~js\n stroke: (d) => Math.sign(d.Close - d.Open)\n~~~\n\nThis function receives as arguments *d* the current datum, and *i* its index in the mark’s data.","pinned":false,"hidden":false,"mode":"md"},{"id":236,"value":"## Filter function 🤞\n\nThe [filter transform](https://observablehq.com/plot/transforms/filter#filter-transform) expects a channel, and works exactly as above. To filter out days when the value has decreased:\n\n~~~js\n fill: (d) => d.Close < d.Open\n~~~\n","pinned":false,"hidden":false,"mode":"md"},{"id":117,"value":"## Channel transforms 🌶\n\nAn alternative way of specifying a [channel](https://observablehq.com/plot/features/marks#marks-have-channels) is through an object with a **transform** method, which is called once on the whole dataset; for example, if you wanted to standardize temperatures (normalizing them by substracting the mean and dividing by the standard deviation):","pinned":false,"hidden":false,"mode":"md"},{"id":116,"value":"Plot.line(sftemp, {\n x: \"date\",\n y: {\n transform: (data) => {\n const values = Plot.valueof(data, \"high\");\n const mean = d3.mean(values);\n const deviation = d3.deviation(values);\n return values.map((d) => (d - mean) / deviation);\n }\n },\n stroke: \"steelblue\"\n}).plot({\n y: { grid: true, label: \"σ\" },\n marks: [Plot.ruleY([0])]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":115,"value":"*Note: the transform operates on the whole dataset; if you want to standardize the data series by series and facet by facet, consider a map transform instead (see below).*","pinned":false,"hidden":false,"mode":"md"},{"id":114,"value":"$30","pinned":false,"hidden":false,"mode":"md"},{"id":113,"value":"viewof useFilter = Inputs.toggle({label: \"use a custom filter\", value: true})","pinned":false,"hidden":false,"mode":"ojs"},{"id":112,"value":"{\n class Dot2 extends Plot.Dot {\n filter(index, channels, values) {\n return index.filter((i) => values.r[i] > 3);\n }\n }\n const MyMark = useFilter ? Dot2 : Plot.Dot;\n return new MyMark(sftemp, {\n x: \"date\",\n y: \"high\",\n r: \"low\"\n }).plot();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":111,"value":"### Render functions 🌶\n\nThe bare minimum that a mark needs to be able to do is to render a SVG fragment. Creating a mark that does not need to be initialized (and thus, doesn’t participate in settings the scales) is as simple as creating a function. For example, to add a watermark or a logo to a chart:","pinned":false,"hidden":false,"mode":"md"},{"id":110,"value":"Plot.plot({\n marks: [\n Plot.frame(),\n Plot.dot(sftemp, {\n x: \"date\",\n y: \"high\",\n fill: \"low\"\n }),\n () => htl.svg``\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":108,"value":"In the chart above, the placement of the image is done haphazardly. But the render function receives as arguments all we need to create the correct positioning, either with respect to the frame’s dimensions (width, height, marginLeft, marginTop, marginRight, marginBottom) or with respect to the scales. These arguments are fully documented with the [marks feature](https://observablehq.com/plot/features/marks). For example: ","pinned":false,"hidden":false,"mode":"md"},{"id":107,"value":"Plot.plot({\n marks: [\n Plot.frame(),\n Plot.dot(sftemp, {\n x: \"date\",\n y: \"high\",\n fill: \"gray\"\n }),\n\n // position the logo wrt the frame’s dimensions\n (index, scales, values, dimensions, context) => {\n const size = 80; // logo image size\n const inset = 10; // separation between logo and frame\n const x = dimensions.width - dimensions.marginRight;\n const y = dimensions.marginTop;\n return htl.svg``\n },\n\n // position the pointing finger wrt the scales\n (index, scales, values, dimensions, context) => {\n const x = scales.x(new Date(\"2011-04-01\"));\n const y = scales.y(45.5);\n return svg`👈 YOU ARE HERE`;\n }\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":106,"value":"Note that an SVG image is a perfectly legal SVG child element inside another SVG image. This allows to create a [plot of plots](https://observablehq.com/@observablehq/plot-of-plots).","pinned":false,"hidden":false,"mode":"md"},{"id":105,"value":"### Composite marks 🤞\n\nThe [marks](https://observablehq.com/plot/features/plots#marks-option) option is a (possibly nested) array of marks. A function can read *data* and *options*, then prepare the data, set some options, and return an array of marks. For instance, here is a [composite mark](https://observablehq.com/plot/features/marks#marks) that uses the [bollinger map method](https://observablehq.com/plot/marks/bollinger#bollinger) to return 21 line marks expressing the uncertainty of a signal:","pinned":false,"hidden":false,"mode":"md"},{"id":104,"value":"function envelopes(data, { k = 2, n, ...options } = {}) {\n return Plot.marks(\n d3.ticks(-1, 1, 21)\n .map((j) =>\n Plot.lineY(\n data,\n Plot.map(\n { y: Plot.bollinger({ k: k * j, n }) },\n { strokeWidth: 1 - 0.95 * Math.abs(j) ** 0.7, ...options }\n )\n )\n )\n );\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":103,"value":"Plot.plot({\n marks: [\n Plot.frame(),\n envelopes(sftemp, {\n k: 1.5,\n x: \"date\",\n y: \"high\"\n }),\n Plot.dot(sftemp, {\n fill: \"brown\",\n r: 1.5,\n x: \"date\",\n y: \"high\"\n })\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":102,"value":"### Conditional marks 🤞\n\nNull(ish) marks are also accepted, and do… nothing. This (quite dull) feature allows a developer to create conditional marks that kick in when an arbitrary criterion is met. For example, the [bollingerY](https://github.com/observablehq/plot/blob/main/src/marks/bollinger.js) composite mark usually returns an area mark to denote the uncertainty band, and a line mark to denote the trailing average of the value. However when the _fill_ option is set to none, it returns null instead of the area mark, and similarly when the _stroke_ option is set to none, it returns null instead of the line mark — thus avoiding unnecessary computations.","pinned":false,"hidden":false,"mode":"md"},{"id":101,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":100,"value":"## Custom fill and stroke 🌶\n\n_gradients, patterns, URI_\n\nTo stroke or fill a shape with an image, a gradient, or a pattern, you can specify the **stroke** or **fill* option as a [funciri](https://developer.mozilla.org/en-US/docs/Web/SVG/Content_type#funciri) — something like \"url(#myRef)\". The referenced element, which has the id myRef, can be anywhere in the document. If you want to create it within the chart, you can use the render function:","pinned":false,"hidden":false,"mode":"md"},{"id":99,"value":"Plot.plot({\n marks: [\n () => htl.svg`\n \n \n \n \n \n `,\n Plot.barY(alphabet, {x: \"letter\", y: \"frequency\", fill: \"url(#gradient)\"}),\n Plot.ruleY([0])\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":98,"value":"See also the [gradient encoding](https://observablehq.com/@observablehq/plot-gradient-encoding) notebook, which shows how to create a gradient informed by the chart’s scales, for consistent encoding.","pinned":false,"hidden":false,"mode":"md"},{"id":97,"value":"## Custom transforms 🌶🌶🌶\n\nThe [transform](https://observablehq.com/plot/features/transforms) option is a generic entry point through which Plot operates on the mark’s data — for grouping, binning, sorting, stacking, etc. It can be specified as a custom function of the *data*, *facets* and Plot *options*, as documented [here](https://observablehq.com/plot/features/transforms#custom-transforms). This is not something that you will usually do when developing a particular chart, but rather if you are working on a new feature for Plot. Transforms operate in data space, before the scales are computed, see initializers.","pinned":false,"hidden":false,"mode":"md"},{"id":96,"value":"## Custom initializers 🌶🌶🌶\n\nThe [initializer](https://observablehq.com/plot/features/transforms#initializer) option is similar to the transform option, but it is called after the scales are computed. It can create new channels, and it can also ask Plot to generate new scales. This is typically where an options transform such as hexbin operates: it reads scaled values of x and y, and generates counts (for example) of the data values that belong to each hexagon. These counts can then be encoded with a new color scale, or radius scale, to create hexagonal bins. Writing a custom initializer is not easy, and will be mostly used by developers who want to create elaborate transformations on scaled data, akin to the dodge or hexbin transforms.","pinned":false,"hidden":false,"mode":"md"},{"id":95,"value":"## Custom projections 🤞\n\nhttps://observablehq.com/plot/features/projections#projection-options\n\nYou can render your maps with any of D3’s extended projections from the [d3-geo-projection](https://github.com/d3/d3-geo-projection) and [d3-geo-polygon](https://github.com/d3/d3-geo-polygon) modules; for instance, [Fuller’s AirOcean](https://observablehq.com/@d3/fullers-airocean) projection:","pinned":false,"hidden":false,"mode":"md"},{"id":94,"value":"Plot.plot({\n width: 560,\n height: 280,\n inset: 10,\n projection: ({ width, height }) => d3.geoAirocean().fitSize([width, height], { type: \"Sphere\" }),\n marks: [\n Plot.graticule(),\n Plot.sphere(),\n Plot.geo(land, { fill: \"currentColor\" })\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":93,"value":"Writing a custom projection can also be fun, for example if you want a base for an [isometric perspective projection](https://observablehq.com/@fil/isometric-projection). ","pinned":false,"hidden":false,"mode":"md"},{"id":92,"value":"## Custom map methods 🌶\n\nThe example below shows a custom map method that implements a standardization of the *y* channel, series by series (and facet by facet). See above for the equivalent standardization on the whole dataset.","pinned":false,"hidden":false,"mode":"md"},{"id":91,"value":"Plot.line(\n sftemp,\n Plot.mapY(\n (values) => {\n const mean = d3.mean(values);\n const deviation = d3.deviation(values);\n return values.map((d) => (d - mean) / deviation);\n },\n {\n x: \"date\",\n y: \"high\",\n stroke: \"steelblue\"\n }\n )\n).plot({\n y: { grid: true, label: \"σ\" },\n marks: [Plot.ruleY([0])]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":240,"value":"## Custom bin and group reducers 🌶\n\nThe [bin](https://observablehq.com/plot/transforms/bin) and [group](https://observablehq.com/plot/transforms/group) transforms aggregate values that share a common trait, reducing them to a single value. The reducer can be a function, that receives for each group the input values (if an input channel is defined), or else the input data.","pinned":false,"hidden":false,"mode":"md"},{"id":248,"value":"Plot.barX(\n penguins,\n Plot.groupY(\n {\n x: (groupData) => groupData.length // equivalent of \"count\"!\n },\n { y: \"species\" }\n )\n).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":257,"value":"Plot.barX(\n penguins,\n Plot.groupY(\n {\n x: (groupValues) => new Set(groupValues).size // equivalent of \"distinct\"!\n },\n { x: \"island\", y: \"species\" }\n )\n).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":244,"value":"This is useful, for example, when creating a detailed title for [interactive tips](https://observablehq.com/plot/features/marks#mark-options).","pinned":false,"hidden":false,"mode":"md"},{"id":261,"value":"Plot.barX(\n penguins,\n Plot.groupY(\n {\n x: \"count\",\n title: (groupData) => `Islands:\\n${[...new Set(groupData.map(d => d.island))].join(\"\\n\")}`\n },\n { y: \"species\", tip: true }\n )\n).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":272,"value":"The same is true for the bin transform, but the reducer function is passed a second argument, with an object describing the bin’s extent:","pinned":false,"hidden":false,"mode":"md"},{"id":269,"value":"Plot.barX(\n penguins,\n Plot.binX(\n {\n fill: \"count\",\n title: (data, {x1, x2}) => `The ${x1}—${x2} bin\\nincludes ${data.length} penguins.`\n },\n { x: \"body_mass_g\", tip: true }\n )\n).plot({color: {scheme: \"Blues\"}, marginBottom: 35})","pinned":true,"hidden":false,"mode":"ojs"},{"id":305,"value":"Both these transforms also accept an object implementing the reduceIndex method, that receives as arguments an index I into the values (or data) S. This is used internally for performance reasons (since it avoids copying the data), but it can also be, say, to compare the median of each group (or bin) with the median of its out-group:","pinned":false,"hidden":false,"mode":"md"},{"id":311,"value":"Plot.rectY(\n penguins,\n Plot.binX(\n {\n fill: \"count\",\n y: {\n reduceIndex: (I, S) => {\n const index = new Set(I); // for faster look-ups\n return (\n d3.median(I, (i) => S[i]) /\n d3.median(S, (d, i) => (index.has(i) ? NaN : d))\n );\n }\n }\n },\n { x: \"body_mass_g\", y: \"body_mass_g\", tip: true }\n )\n).plot({\n y: { label: \"body mass (relative median)\" },\n color: { scheme: \"Blues\" },\n marginBottom: 35\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":90,"value":"## Custom map and window reducers 🌶\n\nThe [window transform](https://observablehq.com/plot/transforms/window) takes a moving window of *n* values in the series, and reduces it to a single value. This allows to compute a moving average, maximum, minimum, etc. When you have more specific asks, you can write a custom reducer as a function. There are three flavor of custom reducers for the map and window transforms.\n\nIn the first example, we’ll use the simplest one: a function that reads the values belonging to the window (or series, in the case of the map transform). To get a better estimate of a moving average over noisy data, our analyst wants to discard the four outermost values (the two highest and the two lowest) before computing the mean. In the chart below, this makes the blue line — where outliers have been removed — more regular than the red line, which uses the usual \"mean\" reducer.","pinned":false,"hidden":false,"mode":"md"},{"id":89,"value":"Plot.plot({\n y: { grid: true, nice: true },\n marks: [\n Plot.dot(sftemp, { x: \"date\", y: \"high\", fill: \"currentColor\", r: 1.5 }),\n Plot.line(\n sftemp,\n Plot.windowY({\n k: 10,\n x: \"date\",\n y: \"high\",\n stroke: \"red\",\n strokeWidth: 0.8\n })\n ),\n Plot.line(\n sftemp,\n Plot.windowY({\n k: 10,\n reduce: (values) => d3.mean(d3.sort(values).slice(2, -2)),\n x: \"date\",\n y: \"high\",\n stroke: \"steelblue\"\n })\n )\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":201,"value":"The map and window transforms can also receive a function to be passed an index and array of channel values, returning new values. This is used internally mostly for performance purposes (since the array of channel values is now the same for all the calls, avoiding thrashing memory); as such, the reducer above could be written as:\n\n~~~js\n reduce: (I, V) => d3.mean(d3.sort(I, (i) => V[i]).slice(2, -2), (i) => V[i]),\n~~~","pinned":false,"hidden":false,"mode":"md"},{"id":211,"value":"Finally, a map reducer can be written as an object that implements the mapIndex method, receiving an index, an array of channel values, and a target array; for instance the _cumsum_ map reducer is designed as a loop though each series I, that adds each (valid) number in turn and fills the target array:\n\n~~~js\n{\n mapIndex(I, S, T) {\n let sum = 0;\n for (const i of I) T[i] = sum += S[i];\n }\n}\n~~~\n\nIf you wanted to count, say, positives and negatives, you could adapt this:\n\n~~~js\n{\n mapIndex(I, S, T) {\n let sum = 0;\n for (const i of I) T[i] = sum += Math.sign(S[i]);\n }\n}\n~~~\n","pinned":false,"hidden":false,"mode":"md"},{"id":87,"value":"## Scale transforms 🌶\n\nA scale transform can be any function mapping the actual data domain to the scale’s domain. For example, multiplying by 100 to transform a ratio (in the [0, 1] interval) into a percentage; or, if the data has temperatures in Fahrenheit (°F), to have a scale use Celsius (°C) instead.\n","pinned":false,"hidden":false,"mode":"md"},{"id":86,"value":"toCelsius = (f) => (f - 32) * (5 / 9)","pinned":true,"hidden":false,"mode":"ojs"},{"id":85,"value":"Note in particular how the ticks, grid, etc. and even the tip contents reflect the transformed values:","pinned":false,"hidden":false,"mode":"md"},{"id":84,"value":"Plot.plot({\n y: { grid: true, transform: toCelsius, label: \"temp. (high, °C)\" },\n color: { legend: true, transform: toCelsius, label: \"temp. (low, °C)\" },\n marks: [Plot.dot(sftemp, { x: \"date\", y: \"high\", fill: \"low\", tip: true })]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":83,"value":"Another typical use case of the scale’s transform option is when you want to facet countries by continent. Here’s a toy example:","pinned":false,"hidden":false,"mode":"md"},{"id":82,"value":"Plot.plot({\n fx: {transform: country => [\"Peru\", \"Ecuador\"].includes(country) ? \"Americas\" : \"Africa\"},\n marks: [\n Plot.barY(\n [\n { country: \"South Africa\", value: 14 },\n { country: \"Zimbabwe\", value: 19 },\n { country: \"Peru\", value: 17 },\n { country: \"Ecuador\", value: 4 },\n { country: \"Nigeria\", value: 8 }\n ],\n { fx: \"country\", fill: \"country\", y: \"value\", tip: true }\n )\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":81,"value":"Plot doesn’t yet allow the creation of custom scales — they must be one of the pre-programmed types. However, when you need a specific scale, it is often the case that it can be mapped to a linear scale with a transform function. For example, to create a [logit scale](https://en.wikipedia.org/wiki/Logit), you would map a linear domain to the logistic domain with:\n\n~~~js\nfunction logit(p) { return Math.log(p / (1 - p)); }\n// x: {transform: logit}\n~~~","pinned":false,"hidden":false,"mode":"md"},{"id":80,"value":"Let’s also mention that an interval (defined as a function) can be used as a scale transform, here aligning all the dots on the start of each week. (However, it is better in that case to use the [interval](https://observablehq.com/plot/features/scales#scale-transforms) scale option instead, which passes more information to the scale.)","pinned":false,"hidden":false,"mode":"md"},{"id":79,"value":"Plot.plot({\n x: { transform: d3.utcWeek },\n marks: [Plot.dot(sftemp.slice(-90, -10), { x: \"date\", y: \"high\" })]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":78,"value":"## Custom color interpolators 🌶\n\nJust like for projections, Plot cannot incorporate all the color palettes in the universe as built-in color schemes. But does this mean we’re missing out on great color palettes, such as Fabio Crameri’s [scientific color maps](https://www.fabiocrameri.ch/colourmaps/)? No!, because we can always transform them into a custom color interpolator. For example, the cell below creates a function which associates the diverging _oleron_ color map to any number between 0 and 1, with [d3.piecewise](https://d3js.org/d3-interpolate/value#piecewise) (but it could be any custom function):","pinned":false,"hidden":false,"mode":"md"},{"id":77,"value":"$32","pinned":true,"hidden":false,"mode":"ojs"},{"id":76,"value":"oleron(0.333) // a light blue color, at 1/3 of the [0, 1] domain","pinned":true,"hidden":false,"mode":"ojs"},{"id":75,"value":"This function can be passed as a color interpolator:","pinned":false,"hidden":false,"mode":"md"},{"id":74,"value":"Plot.plot({\n width: 500,\n aspectRatio: 1,\n color: {\n interpolate: oleron,\n type: \"diverging\",\n legend: true,\n ticks: 5\n },\n marks: [\n Plot.contour({\n x1: -1.5,\n x2: 1.5,\n y1: 2,\n y2: 0,\n fill: (x, y) => 0.05 + Math.atan2(y, x) * (y - x * x),\n thresholds: 30\n })\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":73,"value":"## Custom curves 🌶🌶\n\nCustom curves can be written exactly as with [d3-shape](https://d3js.org/d3-shape/curve#custom-curves); creating a new curve from scratch is beyond the scope of this page, but for funsies here is a quick example where each control point receives noisy coordinates:","pinned":false,"hidden":false,"mode":"md"},{"id":72,"value":"viewof noiseAmplitude = Inputs.range([0, 4], {label: \"noise\", step: 0.1})","pinned":false,"hidden":false,"mode":"ojs"},{"id":71,"value":"Plot.plot({\n marks: [\n Plot.line(sftemp.slice(-90, -10), {\n x: \"date\",\n y: \"high\",\n strokeWidth: 0.5,\n curve: (context) => {\n const curve = d3.curveCardinal(context);\n const noise = d3.randomNormal.source(d3.randomLcg(42))(0, noiseAmplitude);\n return {\n point: (x, y) => curve.point(x + noise(), y + noise()),\n lineStart: () => curve.lineStart(),\n lineEnd: () => curve.lineEnd()\n };\n }\n }),\n Plot.dot(sftemp.slice(-90, -10), {\n x: \"date\",\n y: \"high\",\n fill: \"currentColor\",\n r: 1.5\n })\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":70,"value":"## Custom intervals 🌶\n\nPlot has a lot of built-in intervals, that you can invoke with strings such as \"week\" or even \"2 days\", and use in several options transforms (such as the bin transform), or even as a scale transform. If this is not enough, you can try a custom interval, say to map numbers to a symmetric segment around the integer part of the number; for example, to draw a histogram chart where each bin is centered on the closest integer:","pinned":false,"hidden":false,"mode":"md"},{"id":69,"value":"Plot.rectY(\n Array.from({ length: 400 }, d3.randomNormal.source(d3.randomLcg(42))(0, 3)),\n Plot.binX(\n { y: \"count\" },\n {\n interval: {\n floor: (d) => Math.floor(d + 0.5) - 0.5,\n offset: (d, n = 1) => d + n,\n range: d3.range\n }\n }\n )\n).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":68,"value":"A custom interval must provide the floor, offset and range methods, and floor must be idempotent, so that floor(floor(x)) = floor(x). For another example of a custom range, see https://observablehq.com/@recifs/plot-extended-interval.","pinned":false,"hidden":false,"mode":"md"},{"id":67,"value":"## Custom symbols 🌶🌶\n\nA custom symbol can be specified as an object with a draw method; for instance, to draw a circle, we can use:\n~~~js\n{draw: (context, r) => context.arc(0, 0, Math.sqrt(r), 0, 2 * Math.PI)}\n~~~\nwhich is equivalent to \"circle\". The context accepts [turtle commands](https://observablehq.com/@d3/d3-path). Now, if we want to draw a [rose](https://observablehq.com/@recifs/a-rose-is-a-rose) instead, we can customize this function; we can even consume the size argument and interpret it as a non-size parameter for our symbol:","pinned":false,"hidden":false,"mode":"md"},{"id":66,"value":"Plot.dot(penguins.slice(120, 180), {\n x: \"body_mass_g\",\n y: \"culmen_length_mm\",\n strokeWidth: 0.5,\n stroke: \"species\",\n r: (d, i) => i % 4,\n symbol: {\n draw: (context, size) => {\n const n = 2 * Math.sqrt(size) + 1;\n const r = 25;\n for (let i = 0; i < 360; ++i) {\n const a = (i * Math.PI) / 180;\n const rho = r * Math.sin(n * a);\n context[i === 0 ? \"moveTo\" : \"lineTo\"](rho * Math.cos(a), rho * Math.sin(a));\n }\n context.closePath();\n }\n }\n}).plot({inset: 20, nice: true})","pinned":true,"hidden":false,"mode":"ojs"},{"id":65,"value":"## Custom markers 🌶🌶\n\n[Markers](https://observablehq.com/plot/features/markers#markers) are similar to symbols (they can draw a shape at a certain location), but the API is quite different, expecting a color and returning a SVG [marker element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/marker):","pinned":false,"hidden":false,"mode":"md"},{"id":64,"value":"Plot.plot({\n marks: [\n Plot.line(sftemp.slice(-90, -10), {\n x: \"date\",\n y: \"high\",\n stroke: \"red\",\n marker: (color) => svg``\n }),\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":63,"value":"## Custom vector shapes 🌶🌶\n\nCustom vector shapes are, again, similar to symbols: their draw method is passed a context, length, and radius, and applies [turtle commands](https://observablehq.com/@d3/d3-path) to the context. If you use anchor: start, the shape’s coordinate system’s origin is at the point’s location. The radius parameter allows to create shapes with a secondary dimension (like the base of the triangle for the spike shape).","pinned":false,"hidden":false,"mode":"md"},{"id":62,"value":"Plot.plot({\n marks: [\n Plot.vector(sftemp.slice(-90, -10), {\n x: \"date\",\n y: \"high\",\n length: 20,\n anchor: \"start\",\n r: 4,\n shape: {\n draw: (context, length, radius) => {\n context.moveTo(0, -length / 2);\n context.lineTo(0, length / 2);\n context.arc(0, 0, radius, Math.PI / 2, 2.5 * Math.PI/2)\n }\n }\n })\n ]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":61,"value":"## Custom tick format functions 🤞\n\nAn easy one! The tickFormat option for scales can be specified as a function that takes as input the tick value, and returns a string. For example if you want to return custom abbreviations of day names:","pinned":false,"hidden":false,"mode":"md"},{"id":60,"value":"Plot.plot({\n x: {\n ticks: 20,\n tickFormat: (d) => [\"*\", \"M\", \"Tu\", \"W\", \"Th\", \"F\", \"Sa\"][d.getDay()]\n },\n marks: [Plot.ruleX(sftemp.slice(-25), { x: \"date\" })]\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":59,"value":"## Custom title, subtitle, and caption 🤞\n\nThe **title**, **subtitle**, and **caption** options all accept DOM nodes as well as strings, allowing you to get as funky as you want with tools that generate HTML such as [htl.html](https://github.com/observablehq/htl) and [md](https://github.com/observablehq/stdlib#markdown).","pinned":false,"hidden":false,"mode":"md"},{"id":58,"value":"Plot.plot({\n title: md`## _Who cares about the actual chart?_`,\n subtitle: htl.html`

when it has a good title`,\n marks: [Plot.frame()],\n caption: md`👆 Notice anything missing?`\n}).outerHTML","pinned":true,"hidden":false,"mode":"ojs"},{"id":57,"value":"## Custom document 🌶🌶🌶\n\nThe *context* argument of the render transform has a document property, which defaults to the browser document, and allows to create new nodes. This is useful in specific environments — such as server-side-rendering, like we do for Plot’s documentation website. See the [PlotRender](https://github.com/observablehq/plot/blob/main/docs/components/PlotRender.js) component for vitepress in our repository to see how this works in practice.","pinned":false,"hidden":false,"mode":"md"},{"id":56,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":55,"value":"Plot.raster(\n airports,\n Plot.geoCentroid({\n fill: 1,\n interpolate: function (index, width, height, X, Y, V) {\n // Instantiate a spatial index with d3-quadtree, for faster lookups\n const quadtree = d3.quadtree()\n .x((i) => X[i])\n .y((i) => Y[i])\n .addAll(index);\n\n // Create the output raster\n const R = new Float32Array(width * height);\n\n // For each point in the raster…\n for (let x = 0; x < width; ++x) {\n for (let y = 0; y < height; ++y) {\n // …find the closest sample…\n const i = quadtree.find(x, y);\n // …and save the distance from the pixel to the closest sample\n R[x + y * width] = Math.hypot(X[i] - x, Y[i] - y);\n }\n }\n return R;\n }\n })\n).plot({\n projection: \"albers-usa\",\n color: { scheme: \"Cool\", legend: true, domain: [0, 15], clamp: true }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":54,"value":"import {data as airports} from \"@d3/us-airports-voronoi\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":53,"value":"### random number generators 🌶\n\nThe built-in spatial interpolators also accept a custom random number generator (they default to a fixed-seed randomLcg, for reproducible results). Why should we care about customizing the random numbers? A very important use-case is to base the randomness on _blue noise_, which has good spatial properties. Creating a blue-noise generator is out of scope for this page, but we’ll load one for now from Job van der Zwan’s [Pseudo blue noise](/@jobleonard/pseudo-blue-noise) notebook, and apply it to this map of penguin species.\n\nThe difference is subtle, but note how silky the raster looks with blue noise! When working with numerical values (instead of categories like here), the local average of values computed with a blue-noise generator converges much faster to the true value. This results in more precision in the derived contours, once a little bit of blurring has been applied.","pinned":false,"hidden":false,"mode":"md"},{"id":52,"value":"viewof useBlue = Inputs.toggle({label: \"use blue noise\"})","pinned":false,"hidden":false,"mode":"ojs"},{"id":51,"value":"Plot.raster(penguins, {\n x: \"culmen_length_mm\",\n y: \"culmen_depth_mm\",\n fill: \"species\",\n pixelSize: 0.5,\n interpolate: Plot.interpolatorRandomWalk({\n random: useBlue\n ? (() => {\n const k = 64;\n const blue = noise(k,k);\n return (x, y, z) => {\n x += 17 * z;\n return (\n blue[(Math.floor(x) % k) + k * (Math.floor(y) % k)] /\n (k * k)\n );\n };\n })()\n : undefined\n })\n}).plot()","pinned":true,"hidden":false,"mode":"ojs"},{"id":50,"value":":::tip\nPlot’s built-in interpolators are also JavaScript functions, that can be used as a first step to build a different interpolator, or to compute rasters meant to be used outside of Plot!\n:::","pinned":false,"hidden":false,"mode":"md"},{"id":49,"value":"import {noise} from \"@jobleonard/pseudo-blue-noise\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":48,"value":"- ~~Custom axes? (using explicit rather than implicit axes)~~\n","pinned":false,"hidden":false,"mode":"md"},{"id":47,"value":"## Plot **style** and **className** option 🤞\n\nDon’t forget that you can use Plot’s className and style options to target your chart’s constituents with CSS. The corresponding CSS styles can be defined from inside the chart definition, using the **style** option, if they target the chart’s svg. They can be defined with a more complex stylesheet, that is either returned as a render function mark, or added as an external stylesheet to the document. (Note that each mark can have its own aria label, that can also be used to target a specific mark in the chart.)","pinned":false,"hidden":false,"mode":"md"},{"id":46,"value":"## Post-processing techniques 🌶\n\nPlot returns an HTML figure element, or a raw SVG element containing the chart. Before you return the chart and add it to the DOM, you can manipulate it as any other element. For example, with D3, we can make the dots fade in:","pinned":false,"hidden":false,"mode":"md"},{"id":45,"value":"viewof replay = Inputs.button(\"Replay\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":44,"value":"{\n replay;\n await visibility();\n const chart = Plot.dot(penguins, {\n x: \"culmen_length_mm\",\n y: \"culmen_depth_mm\",\n fill: \"species\",\n stroke: \"white\"\n }).plot();\n d3.select(chart)\n .selectAll(\"circle\")\n .attr(\"r\", 0)\n .transition()\n .delay(200)\n .duration(1500)\n .attr(\"r\", 10);\n return chart;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":43,"value":"This type of post-processing can be as simple as that, or as elaborated as you need!","pinned":false,"hidden":false,"mode":"md"},{"id":0,"value":"## Opting out of scales 🤞\n\nSometimes you will want to apply two color scales, but Plot only accepts one scale at the moment. Don't worry, you are not blocked. Scales can be exported from a chart and reused in another one, so you can build the two scales in different plots, then apply them individually to your mark’s data, and return literal colors.","pinned":false,"hidden":false,"mode":"md"},{"id":41,"value":"chartSpecies = Plot.tickX(penguins, {\n x: \"body_mass_g\",\n stroke: \"species\"\n}).plot({ color: { scheme: \"Category10\", legend: true } })","pinned":true,"hidden":false,"mode":"ojs"},{"id":40,"value":"chartMass = Plot.tickX(penguins, {x: \"body_mass_g\", stroke: \"body_mass_g\"}).plot({color: {scheme: \"Reds\", legend: true}})","pinned":true,"hidden":false,"mode":"ojs"},{"id":39,"value":"combined = {\n const colorMass = chartMass.scale(\"color\").apply;\n const colorSpecies = chartSpecies.scale(\"color\").apply;\n return Plot.plot({\n marginLeft: 80,\n marks: [\n Plot.dot(penguins, {\n x: \"body_mass_g\",\n y: \"species\",\n fill: (d) => colorSpecies(d[\"species\"]),\n dy: -3\n }),\n Plot.dot(penguins, {\n x: \"body_mass_g\",\n y: \"species\",\n fill: (d) => colorMass(d[\"body_mass_g\"]),\n dy: 3\n })\n ]\n });\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":38,"value":"## Opting out of transforms (⁇)\n\n(_e.g._, pre-binned data)","pinned":false,"hidden":false,"mode":"md"},{"id":37,"value":"---\n*data*","pinned":false,"hidden":false,"mode":"md"},{"id":36,"value":"sftemp = FileAttachment(\"sf-temperatures.csv\").csv({typed: true})","pinned":true,"hidden":false,"mode":"ojs"},{"id":35,"value":"d3 = require(\"d3@7\", \"d3-geo-polygon@1\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":34,"value":"countries = FileAttachment(\"countries-110m.json\").json()","pinned":true,"hidden":false,"mode":"ojs"},{"id":33,"value":"land = topojson.feature(countries, countries.objects.land)","pinned":true,"hidden":false,"mode":"ojs"},{"id":151,"value":"import {toc} from \"@mbostock/toc\"","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W34","stdlib":"1","titling":"auto"}