30:T922,theUpdateFunctions = md`## The Update Functions [](#sections) The state of a plot can be anything from a number, string or boolean, to a nested object. tp.update sets a new state whereas tp.mergeUpdate merges the passed object/array with the current state — that should also be an object/array. tp.update uses [Lodash's merge method](https://lodash.com/docs/4.17.15#merge). The first argument of tp.update and tp.mergeUpdate is the plot(s) to update. This can be an element, an iterable of elements (including a D3 selection) or a CSS selector string. If the elements are updatable mark elements (rather than plot SVGs), the plots they belong to are updated. Elements that are neither plots nor updatable elements are ignored. Each plot is only updated once. For example, if all bars in a plot have class bar, we could use tp.update('.bar', newState) and the plot will only be updated once. If an update function is called with only two arguments, the second argument is the state. If three arguments are passed, the third argument is the state and the second argument explicitly specifies the elements to be updated. Like the first argument, this can be an element, an iterable of elements or a CSS selector string. Only updatable elements that appear in one of the plots specified in the first argument are updated — other elements are ignored. Elements are only updated once. When an update function is called with two arguments, the plots are updated in the order in which they are passed/selected; within each plot, the mark elements are updated in the order in which they were created. When an update function is called with three arguments, the elements specified by the second argument are updated in the order in which they are passed/selected. __Note__: The initial state of a plot (set with the state method) is deep cloned using [Lodash's cloneDeep method](https://lodash.com/docs/4.17.15#cloneDeep). When the plot method is called, the initial state is deep cloned again — so if a plot object is reused, the plots _do not_ share a state object. When a plot's state is updated with tp.update, the new state is deep cloned.`31:T48b,limitations = md`## Limitations [](#sections) The following limitations apply to updates (most are just features still to be implemented rather than intrinsic limitations): * arc marks cannot be updated. * Notes cannot be updated, nor do they change when the corresponding mark is updated. Use text marks for updatable text. * The following channels cannot be updated: xOffset, yOffset, class, name, click, mousenter, mouseleave, subplot — the marks of subplots _can_ be updated. * No channels of a rect mark being used for a subplot can be updated. * Only channel values can be updated — options cannot be updated. Updates only affect marks; they do not affect axis limits, data maps, the legend etc. However, the initial state _is_ used when the plot is first drawn so _does_ affect all of these things. Remember to set limits and data maps explicitly where appropriate — e.g. if there are categorical values in updates that are not used when the plot is first drawn. `32:T47f,missingAndInvalidData = md`## Missing and Invalid Data [](#sections) When the plot is first drawn (regardless of whether any channels depend on state), Teapot handles invalid and missing data as described in the [main Teapot docs](https://observablehq.com/@gjmcn/teapot-docs). For updates, the behavior is different: * single-mark types (e.g. line), channels: x, xx, y, yy: values are not checked so should not be null, undefined, NaN, Infinity or -Infinity. * all other cases: the channel is not updated if the new value is null or undefined (but other channels are still updated); there is no special handling of NaN, Infinity and -Infinity, so these should be handled explicitly before updating. When the mark option missing is 'skip' or 'gap', the list of missing data points is fixed when the plot is first drawn. Updating the values of these missing points does not affect the plot.`33:[] 2e:{"title":"Teapot Updates: Docs","cells":[{"id":0,"value":"md`# Teapot Updates: Docs\n\nUpdates allow channel values to be modified and hence, allow plots to be interactive or animated.\n\n__Note__: Updates provide the foundation for interactive plots. Many types of interaction are easily added using updates, but some (tooltips, interactive legends and brushing in particular) require additional features that are still to be implemented.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2576,"value":"sections = md`## Sections\n\n* [State](#state)\n* [The Update Functions](#theUpdateFunctions)\n* [Limitations](#limitations)\n* [Multiple Plots](#multiplePlots)\n* [Subplots](#subplots)\n* [Missing And Invalid Data](#missingAndInvalidData)\n* [Transitions](#transitions)\n* [The front Channel](#front)\n* [Modifying Plots In Observable](#modifyingInObservable)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1203,"value":"state = md`## State [](#sections)\n\nTo make a channel _updatable_, we use an accessor function, but instead of the normal two parameters, we use three: (d, i, s) => ... The first and second parameters are the datum and index as usual; the third parameter is the plot's _state_. The inital state is null by default, but can be set using the the state method. After drawing the plot, we pass tp.update the plot SVG and the new state to update the plot:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":999,"value":"sinPlot = tp\n .line({\n data: 101,\n x: d => d / 10,\n y: (d, i, s) => Math.sin(d / 10 * s),\n curve: 'natural'\n })\n .option({width})\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1002,"value":"viewof sinSlider = Inputs.range([1, 10], {step: 0.2, value: 1})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1003,"value":"tp.update(sinPlot, sinSlider),\n md`_There is another cell here that links the plot and the slider. See the [Modifying Plots In Observable](#modifyingInObservable) section for alternative approaches to this._`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":1222,"value":"md`A typical use of state is where each datum contains more information than is plotted, and the state controls what is actually shown:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":617,"value":"scores = [\n {student: 'Alex', subject: 'art', score: 87},\n {student: 'Alex', subject: 'bio', score: 72},\n {student: 'Alex', subject: 'chem', score: 60},\n {student: 'Billie', subject: 'art', score: 54},\n {student: 'Billie', subject: 'bio', score: 59},\n {student: 'Billie', subject: 'chem', score: 46},\n {student: 'Casey', subject: 'art', score: 21},\n {student: 'Casey', subject: 'bio', score: 87},\n {student: 'Casey', subject: 'chem', score: 91},\n {student: 'Dana', subject: 'art', score: 52},\n {student: 'Dana', subject: 'bio', score: 82},\n {student: 'Dana', subject: 'chem', score: 68},\n];","pinned":false,"hidden":false,"mode":"ojs"},{"id":939,"value":"byStudent = tp.group(scores, 'student')","pinned":true,"hidden":false,"mode":"ojs"},{"id":633,"value":"subjectPlot = tp\n .vBar({\n data: byStudent,\n x: d => d.name, \n y: (d, i, s) => d.group.find(d => d.subject === s).score\n })\n .state('art')\n .option({limits: [,,,100]})\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":654,"value":"viewof subjectRadio = Inputs.radio(['art', 'bio', 'chem'], {value: 'art', label: 'Subject'})","pinned":false,"hidden":false,"mode":"ojs"},{"id":662,"value":"tp.update(subjectPlot, subjectRadio),\n md`_(this cell links the plot and radio buttons)_` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":2446,"value":"md`With grouped data, applying tp.lookup inside each group often simplifies the plot code:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1718,"value":"byStudentLookup = byStudent.map(({name, group}) => ({name, ...tp.lookup(group, 'subject', 'score')}))","pinned":true,"hidden":false,"mode":"ojs"},{"id":2114,"value":"lookupPlot = tp\n .vBar({\n data: byStudentLookup,\n x: d => d.name, \n y: (d, i, s) => d[s]\n })\n .state('art')\n .option({limits: [,,,100]})\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":2117,"value":"viewof lookupRadio = Inputs.radio(['art', 'bio', 'chem'], {value: 'art', label: 'Subject'})","pinned":false,"hidden":false,"mode":"ojs"},{"id":2120,"value":"tp.update(lookupPlot, lookupRadio),\n md`_(this cell links the plot and radio buttons)_` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":1327,"value":"md`The data-and-state approach is flexible. For example, we can mutate the data directly (Teapot references the data; it does not copy it) and only include a state parameter to indicate that the channel is updatable:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1335,"value":"// do everything in one cell since Observable doesn't like mutation\n{\n const fruit = [\n {name: 'apple', eat: 3},\n {name: 'banana', eat: 2},\n {name: 'cherry', eat: 5}\n ];\n \n const container = DOM.element('div');\n \n const svg = tp\n .vBar({\n data: fruit,\n x: d => d.name,\n y: (d, i, s) => d.eat\n })\n .option({clip: true})\n .plot(container);\n \n const btn = container.appendChild(Inputs.button('Eat a cherry'))\n btn.addEventListener('input', () => {\n fruit[2].eat -= 1;\n tp.update(svg, null);\n });\n \n return container; \n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1362,"value":"md`Alternatively, we can just use the data to generate the correct number of marks and then pass everything as state:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1365,"value":"oneBarPlot = tp\n .data(1)\n .state(5)\n .hBar((d, i, s) => s, 0)\n .option({height: 80, yClean: true})\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1417,"value":"viewof oneBarSlider = Inputs.range([0, 5], {step: 0.05, value: 5})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1419,"value":"tp.update(oneBarPlot, oneBarSlider),\n md`_(this cell links the plot and slider)_`;","pinned":false,"hidden":false,"mode":"ojs"},{"id":1155,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":1505,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":735,"value":"multiplePlots = md`## Mulitple Plots [](#sections)\n\nEach plot has its own state. To link multiple plots, give them the same initial state and updates. Try hovering over a bar in the following example (and note how we use the event channels mouseenter and mouseleave to trigger updates from inside the plots):`","pinned":false,"hidden":false,"mode":"ojs"},{"id":776,"value":"tp.facet(byStudent, function(data, student) {\n this\n .vBar({\n data,\n x: d => d.subject, \n y: d => d.score,\n fill: (d, i, s) => d.subject === s ? 'purple' : 'gray',\n mouseenter: d => tp.update('.student-plot', d.subject),\n mouseleave: d => tp.update('.student-plot', null)\n })\n .option({\n limits: [,,,100],\n width: 160,\n height: 180,\n plotTitle: student,\n class: 'student-plot',\n yTickStep: 20\n })\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":771,"value":"subplots = md`## Subplots [](#sections)\n\nSubplots do not have their own state; they see the state of the top-level plot. This makes it easy to coordinate changes across subplots:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":744,"value":"tp.rect({\n data: byStudent,\n x: (d, i) => i,\n subplot: function(data) {\n this.vBar({\n data: data.group,\n x: d => d.subject,\n y: d => d.score,\n fill: (d, i, s) => d.subject === s ? 'purple' : 'gray',\n mouseenter: function(d) { tp.update(this, d.subject) },\n mouseleave: function(d) { tp.update(this, null) }\n })\n .option({\n limits: [,,,100],\n plotTitle: data.name,\n yTickStep: 20\n })\n }\n })\n .option({ // match the multiple plots version above\n width: 640,\n height: 180,\n limits: '_data',\n clean: true,\n plotSpace: 0\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1575,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":1908,"value":"transitions = md`## Transitions [](#sections)\n\nThe transition channels are delay, duration and ease. delay and duration are in milliseconds (default: 0); ease should be a valid CSS [transition timing function](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) (default: 'linear'). When transition channels are used, the other channels use the specified transition.\n\nCurrently, only circle, hBar, vBar, rect and text marks can use the transition channels. Furthermore, the text channel does not transition — changes to text content are instant.\n\nSince channels are used for transitions, each mark can have its own transition. Also, transitions are updatable — i.e. they can depend on state:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1916,"value":"transSubjectPlot = tp\n .vBar({\n data: byStudentLookup,\n x: d => d.name, \n y: (d, i, s) => d[s],\n fill: (d, i, s) => d[s] > 60 ? 'forestgreen' : 'gray',\n delay: (d, i, s) => d[s] > 60 ? 500 : 0,\n duration: 500,\n ease: 'ease'\n })\n .state('art')\n .option({limits: [,,,100]})\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1918,"value":"viewof transSubjectRadio = Inputs.radio(['art', 'bio', 'chem'], {value: 'art', label: 'Subject'})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1920,"value":"tp.update(transSubjectPlot, transSubjectRadio),\n md`_(this cell links the plot and radio buttons)_` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":2283,"value":"front = md`## The front Channel [](#sections)\n\nWhen updating a mark element, use a state-based front channel to move the element in front or behind the other mark elements. The value of front is converted to a number if it is not one already:\n\n* negative: move to back\n* zero: do not move\n* positive: move to front\n\nHover on a bar in the following example to bring it to the front:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2312,"value":"tp.vBar('~subject', '~score', {\n data: byStudent[0].group,\n fill: '~subject',\n fillScheme: tp.cat,\n fillLegend: false,\n size: 1.2,\n front: (d, i, s) => d.subject === s,\n mouseenter: function(d) { tp.update(this, d.subject) }\n })\n .plot();","pinned":false,"hidden":false,"mode":"ojs"},{"id":2369,"value":"md`__Note__: front moves elements instantly — they do not [transition](#transitions).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":8,"value":"modifyingInObservable = md`## Modifying plots in Observable [](#sections)\n\nThe following examples show different approaches to modifying a plot in Observable. \n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"md`### New plot each time state changes\n\nA particularly simple approach is to bypass updates and state, and reference other cells directly. This approach does not actually modify a plot; it creates a new plot each time one of the referenced cells changes:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1808,"value":"subjectPlot2 = tp\n .vBar({\n data: byStudentLookup,\n x: d => d.name, \n y: d => d[subjectRadio2]\n })\n .option({limits: [,,,100]})\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1805,"value":"viewof subjectRadio2 = Inputs.radio(['art', 'bio', 'chem'], {value: 'art', label: 'Subject'})","pinned":false,"hidden":false,"mode":"ojs"},{"id":20,"value":"md`### Using tp.update, tp.mergeUpdate\n\nTo modify an existing plot, we need to use tp.update or tp.mergeUpdate. There are various ways to do this in Observable:\n\n* A cell for the plot, a cell for the input, and a cell to link the plot and the input. This approach is used in the earlier sections.\n\n* A cell for the plot and a cell for the input; add an event listener to the input:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":320,"value":"oneStudentPlot = tp\n .vBar('~subject', '~score', {\n data: byStudent[0].group,\n fill: '~subject',\n fillScheme: tp.cat,\n fillLegend: false,\n size: (d, i, s) => s,\n })\n .state(0.9)\n .plot();","pinned":false,"hidden":false,"mode":"ojs"},{"id":350,"value":"{\n const slider = Inputs.range([0.05, 1.2], {step: 0.05, value: 0.9, label: 'size'});\n slider.addEventListener('input', function() {\n tp.update(oneStudentPlot, this.value)\n });\n return slider;\n} ","pinned":false,"hidden":false,"mode":"ojs"},{"id":388,"value":"md`* Plot and input in the same cell:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":284,"value":"{\n const container = DOM.element('div');\n \n const plotObj = tp\n .vBar('~subject', '~score', {\n data: byStudent[0].group,\n fill: '~subject',\n fillScheme: tp.cat,\n fillLegend: false,\n size: (d, i, s) => s\n })\n .state(0.9)\n .plot(container)\n \n const slider = container.appendChild(Inputs.range([0.05, 1.2], {step: 0.05, value: 0.9, label: 'size'}))\n slider.addEventListener('input', function() {\n tp.update(plotObj, this.value)\n });\n\n return container; \n} ","pinned":false,"hidden":false,"mode":"ojs"},{"id":62,"value":"md`---`","pinned":false,"hidden":false,"mode":"ojs"},{"id":69,"value":"tp = (await import('https://cdn.skypack.dev/@gjmcn/teapot@0.3.2')).tp","pinned":false,"hidden":false,"mode":"ojs"},{"id":2574,"value":"html`\n\n`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}