30:T43b,bin = md`## tp.bin, tp.binCount [](#top) tp.bin takes an array followed by arguments property0, limits0, property1, limits1, ... Each property argument is a property name, index or accessor function. tp.bin is somewhat unusual: accessor functions are only passed the element, values to bin must be finite numbers, and there is currently no built-in option for handling missing values — so preprocess data as appropriate. Each limits argument should be an array of bin limits (finite numbers). For example, [25, 30, 35, 40] corresponds to 3 bins of width 5 with inclusive upper limits 30, 35 and 40. Rather than passing an array of limits directly, we can use a callback function; this is passed the minimum and maximum of the values being binned, as well as the values as an array. The callback should return an array of bin limits. tp.bin returns an array; each element is an object containing the bin information and bin content:`31:T481,md`If passed three arguments, tp.facet passes the first two arguments to tp.group, then passes each group to the third argument — a callback function. The callback is passed the group (an array), the group name, and the index; inside the callback, this is a new plot object. Do not call the plot method inside the callback; plot is called automatically and the resulting SVG elements are added to an HTML div element. tp.facet returns an object with a plot method; plot returns the div containing the SVGs. If plot is passed an HTML element, the div is inserted into the element (after any current content). If plot is passed a CSS selector string, the div is inserted into the first corresponding element. If the data has already been grouped, call tp.facet with two arguments: the grouped data and the callback function. __Note__: Regardless of whether we use tp.facet or tp.each, the container div can be styled using standard CSS. For more complex layouts, use subplots.`32:Tc46,md`tp.hStack and tp.vStack take an array of objects/arrays (the data) and an options object. The options for tp.vStack are: * x: property/index to group/bin. * y: property/index to appear on y-axis — omit for a frequency count on the stack option. * stack: property/index to stack. * binLimits: if binning on x, the bin limits (see [tp.bin](#bin)). * missing: how to handle missing (i.e. null or undefined) x, y or stack values: * 'throw' (default): throw an error * 'skip': ignore the datum * 'zero': use 0 for missing y values; throw for other missing values * order: stacking order: * 'none' (default): order by first appearance of stack values in data * 'asc' (ascending), 'desc' (descending), 'appearance', 'insideOut', 'reverse' — see [D3 Shape: Stack Orders](https://github.com/d3/d3-shape#stack-orders) * offset: * 'none' (default): applies a zero baseline * 'expand', 'diverging', 'silhouette', 'wiggle' — see [D3 Shape: Stack Offsets](https://github.com/d3/d3-shape#stack-offsets) * rows: if truthy, returns row-based data (array of objects); otherwise, returns column-based data (object of arrays). See below for more details. __Notes__: * The options for tp.hStack are the same except that the x and y options are swapped. * stack is the only required option. * Each of the x, y and stack options must be a property name or index — they cannot be accessor functions (for now at least). * If the y option is used with tp.vStack and there are multiple rows with the same x and stack values, only the last such row is used. tp.hStack behaves similarly. If the rows option is truthy, tp.hStack and tp.vStack return an array of objects — only one object when not grouping/binning. The objects have properties named after the channels they are typically used with. For tp.vStack, the objects have properties y, yy and fill. If grouping, objects also have an x property; if binning, the objects have lower, upper, middle and range properties (see [tp.bin](#bin)). When tp.hStack is used, the x and y properties are swapped. If the rows option is falsy, tp.hStack and tp.vStack return a single object with the properties described for row-based results, but each property value is an array. `33:T4f1,lookup = md`## tp.lookup [](#top) tp.lookup converts an array to an object. The arguments of tp.lookup are: * An array (or actually, any iterable); typically its elements are objects or arrays. * A property name or index to use for the lookup, or alternatively, a callback function that returns the lookup value. The function is called for each element, and is passed the element, the index and the array. (The lookup values should be unique.) * [optional] A property name or index: the value of the property is used instead of the element in the result. Alternatively, this argument can be a callback function: it is passed the element, index and array; the returned value is used instead of the element in the result. Transforming data with tp.lookup can simplify plotting. In particular, we often apply tp.lookup to an external dataset (i.e. not the dataset attached to the plot/mark) so that we can look up rows of the external data by a specific property. tp.lookup is also commonly used with grouped data (particularly when using [updates](https://observablehq.com/@gjmcn/teapot-updates-docs)) where we apply tp.lookup within each group: `34:[] 2e:{"title":"Teapot Helpers: Docs","cells":[{"id":0,"value":"top = md`# Teapot Helpers: Docs\n\nThe helper functions:\n\n* [tp.group, tp.groupCount](#group)\n* [tp.bin, tp.binCount](#bin)\n* [tp.each](#each)\n* [tp.layer](#layer)\n* [tp.facet](#facet)\n* [tp.hStack, tp.vStack](#stack)\n* [tp.lookup](#lookup)\n* [tp.call](#call)\n* [tp.range, tp.linSpace](#range)\n\n__Note__: Since mark methods use a '~' prefix to indicate a property name or index, a '~' prefix can also be used when passing a property name or index to a helper function — the '~' is ignored.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":38,"value":"group = md`## tp.group, tp.groupCount [](#top)\n\ntp.group takes an array followed by at least one property name, index or accessor function to group on — accessor functions are passed an element, index and the array.\n\ntp.group returns an array; each element is an object containing the group name(s) and the group:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"fruitLog = [\n {month: 'Jan', fruit: 'apple', eat: 6},\n {month: 'Jan', fruit: 'banana', eat: 4},\n {month: 'Jan', fruit: 'cherry', eat: 8},\n {month: 'Feb', fruit: 'apple', eat: 2},\n {month: 'Feb', fruit: 'banana', eat: 3},\n {month: 'Feb', fruit: 'cherry', eat: 5},\n {month: 'Mar', fruit: 'apple', eat: 0},\n {month: 'Mar', fruit: 'banana', eat: 7},\n {month: 'Mar', fruit: 'cherry', eat: 5},\n {month: 'Apr', fruit: 'apple', eat: 3},\n {month: 'Apr', fruit: 'banana', eat: 5},\n {month: 'Apr', fruit: 'cherry', eat: 7}\n];","pinned":false,"hidden":false,"mode":"ojs"},{"id":51,"value":"tp.group(fruitLog, 'fruit')","pinned":true,"hidden":false,"mode":"ojs"},{"id":461,"value":"md`When data is grouped on multiple dimensions, the group name properties are name_0, name_1, ...`","pinned":false,"hidden":false,"mode":"ojs"},{"id":55,"value":"tp.group(fruitLog, 'fruit', 'month')","pinned":true,"hidden":false,"mode":"ojs"},{"id":216,"value":"md`tp.group has no special behavior for null and undefined values — there will simply be groups with the name null and undefined. tp.group throws if any group names are non-finite numbers (NaN, Infinity or -Infinity).\n\ntp.groupCount is the same as tp.group, except that the result includes the size of each group (as the count property) rather than the group itself.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":202,"value":"tp.groupCount(fruitLog, 'fruit')","pinned":true,"hidden":false,"mode":"ojs"},{"id":985,"value":"md`__Notes__:\n\n* tp.group and tp.groupCount use the [SameValueZero](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#same-value-zero_equality) algorithm.\n\n* The index argument of accessor functions is the index within the group. Hence, the index argument only corresponds to the orginal index of the datum at the first level of grouping.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":209,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":240,"value":"tp.bin(fruitLog, 'eat', [0, 2, 4, 6, 8])","pinned":true,"hidden":false,"mode":"ojs"},{"id":242,"value":"md`tp.binCount is the same as tp.bin, except that the result includes the size of each bin (as the count property) rather than the bin itself:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":301,"value":"points = [\n [5.3, 34], [8.2, 15], [1.2, 91], [6.4, 33], [4.8, 57],\n [2.8, 91], [4.3, 49], [5.0, 48], [1.3, 87], [7.2, 35],\n [6.6, 48], [3.4, 57], [2.9, 76], [2.4, 68], [4.9, 52]\n]","pinned":false,"hidden":false,"mode":"ojs"},{"id":249,"value":"pointsBinX = tp.binCount(points, 0, tp.range(0, 10, 2))","pinned":true,"hidden":false,"mode":"ojs"},{"id":255,"value":"md`The result of 1-dimensional binning is often plotted as a histogram:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":263,"value":"tp.vBar({\n data: pointsBinX,\n size: d => d.range * 0.98, \n x: d => d.middle, \n y: '~count',\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":405,"value":"md`When data is binnned on multiple dimensions, the bin information properties have suffixes _0, _1, ...`","pinned":false,"hidden":false,"mode":"ojs"},{"id":319,"value":"pointsBinXY = tp.binCount(points, 0, tp.range(0, 10, 2), 1, tp.range(0, 100, 20))","pinned":true,"hidden":false,"mode":"ojs"},{"id":294,"value":"md`The result of 2-dimensional binning is often plotted as a histogram heatmap :`","pinned":false,"hidden":false,"mode":"ojs"},{"id":303,"value":"tp.rect({\n data: pointsBinXY,\n width: '~range_0',\n height:'~range_1',\n x: d => d.middle_0,\n y: d => d.middle_1,\n fill: '~count',\n fillScheme: d3.interpolateBlues,\n fillLimits: [0]\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1001,"value":"md`__Notes__:\n\n* To bin dates, convert the limits and values to numbers. \n\n* tp.bin and tp.binCount throw an error if the extent of the limits does not cover the values being binned.\n\n* Empty bins are not included in the result of tp.bin and tp.binCount.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":14,"value":"each = md`## tp.each [](#top)\n\n_tp.each can be used as a static method (a new plot object is created) or as an instance method of an existing plot object._ \n\ntp.each takes an array, and a function to apply to each element of the array. The function is passed the element, its index and the array; inside the function, this is the plot object.\n\nA typical use case of tp.each is to add multiple lines or bands to the same plot:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":35,"value":"fruitColors = ['green', 'gold', 'crimson']","pinned":false,"hidden":false,"mode":"ojs"},{"id":33,"value":"tp.each(tp.group(fruitLog, 'fruit'), function({group, name}, i) {\n this.line({\n data: group,\n x: '~month',\n y: '~eat',\n stroke: fruitColors[i],\n note: name,\n noteColor: '_stroke',\n fontSize: 13\n })\n })\n .option({\n width: 400,\n limits: ['_data', '_data'],\n plotSpace: [, 50]\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":145,"value":"md`__Note__: For the common case of iterating over groups and adding marks to the same plot (as in the above example), [tp.layer](#layer) is simpler than tp.each.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":107,"value":"layer = md`## tp.layer [](#top)\n\n_tp.layer can be used as a static method (a new plot object is created) or as an instance method of an existing plot object._ \n\nIf passed three arguments, tp.layer passes the first two arguments to tp.group, then passes each group to the third argument — a callback function. The callback is passed the group (an array), the group name, and the index; inside the callback, this is the plot object.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":110,"value":"tp.layer(fruitLog, 'fruit', function(group, name, i) {\n this.line({\n data: group,\n x: '~month',\n y: '~eat',\n stroke: fruitColors[i],\n note: name,\n noteColor: '_stroke',\n fontSize: 13\n })\n })\n .option({\n width: 400,\n limits: ['_data', '_data'],\n plotSpace: [, 50]\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":114,"value":"md`If the data has already been grouped, call tp.layer with two arguments: the grouped data and the callback function.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":96,"value":"facet = md`## tp.facet [](#top)\n\nTo create multiple plots, we can use subplots (see the [main Teapot docs](https://observablehq.com/@gjmcn/teapot-docs)) or create separate plots. Subplots are more powerful, but more work; separate plots are simple, but we need to manually add each plot to the DOM:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":135,"value":"{\n const container = DOM.element('div');\n \n tp.group(fruitLog, 'fruit').forEach(({group, name}, i) => {\n tp.line({\n data: group,\n x: '~month',\n y: '~eat',\n stroke: fruitColors[i]\n })\n .option({\n width: 200,\n height: 200,\n limits: ['_data', '_data', 0, 8],\n plotTitle: name\n })\n .plot(container);\n });\n \n return container;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":140,"value":"md`For the common case of iterating over groups and adding a separate plot for each group (as in the above example), tp.facet can be used:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":157,"value":"tp.facet(fruitLog, 'fruit', function(group, name, i) {\n this\n .line({\n data: group,\n x: '~month',\n y: '~eat',\n stroke: fruitColors[i]\n })\n .option({\n width: 200,\n height: 200,\n limits: ['_data', '_data', 0, 8],\n plotTitle: name\n })\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":154,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":584,"value":"stack = md`## tp.hStack, tp.vStack [](#top)\n\ntp.hStack and tp.vStack transform data so that it is easily plotted as a stacked bar or area chart:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":588,"value":"tp.vBar({\n ...tp.vStack(fruitLog, {\n x: 'month',\n y: 'eat',\n stack: 'fruit',\n order: 'reverse' // apple bars at top to match legend\n }),\n fillScheme: fruitColors,\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":542,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":620,"value":"md`Here are some more examples of stacked charts. These examples use the well-known cars dataset:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":356,"value":"cars = (await require(\"@observablehq/cars\")).filter(d => d.Horsepower)","pinned":false,"hidden":false,"mode":"ojs"},{"id":635,"value":"md`* tp.hStack with no x (so frequency count on the stack option) or y (so no grouping or binning — a single bar):`","pinned":false,"hidden":false,"mode":"ojs"},{"id":880,"value":"tp.hBar({\n ...tp.hStack(cars, {stack: 'Origin'}),\n fillScheme: tp.cat\n })\n .option({\n yClean: true,\n width: 500,\n height: 80,\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":673,"value":"md`* An alternative version of the above plot:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":883,"value":"tp.hBar({\n data: tp.hStack(cars, {stack: 'Origin', rows: true}),\n x: '~x',\n xx: '~xx',\n fill: '~fill',\n fillScheme: tp.cat,\n note: d => `${d.fill} ${d.x - d.xx}`,\n hAlign: 'end',\n noteXOffset: -6,\n noteColor: '#f0f0f0',\n fontSize: 12\n })\n .option({\n yClean: true,\n xTickValues: [250, 321, 400],\n xAxisPosition: 'top',\n xAxis: false,\n xTitle: false,\n legend: false,\n width: 500,\n height: 80\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":729,"value":"md`* Binned x-axis:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":735,"value":"tp.vBar({\n data: tp.vStack(cars, {\n x: 'Weight_in_lbs',\n binLimits: tp.range(0, 6000, 250),\n stack: 'Origin',\n rows: true,\n order: 'reverse'\n }),\n x: '~middle',\n y: '~y',\n yy: '~yy',\n size: d => d.range * 0.98,\n fill: '~fill',\n fillScheme: tp.cat\n })\n .option({\n width: 440,\n height: 300,\n xTitle: 'Weight_in_lbs',\n yTitle: 'Cars',\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":776,"value":"md`* Stacked area chart:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":777,"value":"tp.layer(tp.vStack(cars, {\n x: 'Year',\n stack: 'Origin',\n rows: true,\n order: 'reverse'\n }), 'fill', function(data, origin, i) {\n this.hBand({\n data,\n x: '~x',\n y: '~y',\n yy: '~yy',\n fill: i ,\n fillScheme: tp.cat,\n fillOpacity: 0.85,\n note: origin,\n noteColor: '_fill',\n fontSize: 13,\n })\n })\n .option({\n limits: [,1982],\n height: 300,\n width: 500,\n paneSpace: [,50],\n xTickStep: 1,\n xTitle: false,\n yTitle: false,\n plotTitle: 'Cars',\n plotTitleAlign: 'start'\n })\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":941,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":954,"value":"fruitGroup = tp.group(fruitLog, 'fruit')","pinned":true,"hidden":false,"mode":"ojs"},{"id":944,"value":"fruitGroup.map(({name, group}) => tp.lookup(group, 'month'))","pinned":true,"hidden":false,"mode":"ojs"},{"id":946,"value":"md`Here is an example of applying tp.lookup inside each group and transforming fruitGroup to 'wide data':`","pinned":false,"hidden":false,"mode":"ojs"},{"id":948,"value":"fruitGroup.map(({name, group}) => ({fruit: name, ...tp.lookup(group, 'month', 'eat')}))","pinned":true,"hidden":false,"mode":"ojs"},{"id":1350,"value":"call = md`## tp.call [](#top)\n\n_tp.call can be used as a static method (a new plot object is created) or as an instance method of an existing plot object._ \n\n\\`tp.call\\` is passed a callback function and (optionally) arguments to pass to the callback. Inside the callback, \\`this\\` is the plot object.\n\n\\`tp.call\\` returns the plot object:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1357,"value":"function addThreshold(thresh, color) {\n this.line([0, 10], thresh, {stroke: color});\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1355,"value":"tp.vBar({\n data: pointsBinX,\n size: d => d.range * 0.98, \n x: d => d.middle, \n y: '~count',\n })\n .call(addThreshold, 3.5, 'limegreen')\n .plot()","pinned":false,"hidden":false,"mode":"ojs"},{"id":909,"value":"range = md`## tp.range, tp.linSpace [](#top)\n\ntp.range returns an array of equally spaced numbers. tp.range takes three arguments: start, end and step. step is 1 by default:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":918,"value":"tp.range(3, 11, 2)","pinned":true,"hidden":false,"mode":"ojs"},{"id":924,"value":"tp.range(0, -2.3, -0.5)","pinned":true,"hidden":false,"mode":"ojs"},{"id":901,"value":"md`tp.linSpace is like tp.range, but the third argument of tp.linSpace (which should be a non-negative integer) is the number of steps:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":921,"value":"tp.linSpace(0, 100, 6)","pinned":true,"hidden":false,"mode":"ojs"},{"id":932,"value":"tp.linSpace(2, -1, 7)","pinned":true,"hidden":false,"mode":"ojs"},{"id":914,"value":"md`__Note__: Due to floating-point arithmetic, the final element of a range created with tp.linSpace may not be identical to the end argument.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":5,"value":"md`---`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2,"value":"tp = (await import('https://cdn.skypack.dev/@gjmcn/teapot@0.3.2')).tp","pinned":false,"hidden":false,"mode":"ojs"},{"id":1087,"value":"html`\n\n`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W34","stdlib":"1","titling":"auto"}