31:[] 2f:{"title":"Density Plot Documentation","cells":[{"id":5,"value":"md`# Density Plot Documentation\n\nStandard charts such as scatterplots and line charts have difficulties scaling as data increases due to issues with performance and overplotting. Density plots are an alternative that can handle larger volumes of data, often more quickly.\n\nThis notebook documents a [density plot library](https://observablehq.com/@twitter/density-plot) which implements methods for computing and plotting density arrays. Usage examples are collected in this [notebook collection](https://observablehq.com/collection/@twitter/density).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":416,"value":"importStatement","pinned":false,"hidden":false,"mode":"ojs"},{"id":958,"value":"densityPlot(seriesDensity(width, 100)).drawAxes(false)(\n Array.from({ length: 50 }, (_, i) =>\n Array.from({ length: 150 }, (_, j) => Math.sin(0.08 * i + 0.1 * j))\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":415,"value":"md`\n## API Reference\n\n- [\\`densityPlot\\`](#densityPlotDoc) – high-level interface to quickly create a density plot.\n- [\\`pointDensity\\`](#pointDensityTitle) – compute density arrays from *(x, y)* points.\n- [\\`seriesDensity\\`](#seriesDensityDoc) – compute density arrays from time series.\n- [\\`cacheInterpolator\\`](#cacheInterpolatorDoc) - convenience function for efficient color interpolation\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":104,"value":"densityPlotDoc = md`[#](#densityPlotDoc) **densityPlot**([*density*, [*size*]]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nConstructs a new plot generator with default settings. If a [density estimator](#densityEstimationHeader) is specified, sets the [density estimator](#densityPlotDensityDoc). If a *size* is specified, sets the [size](#densityPlotSizeDoc) of the plot canvas.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":177,"value":"densityPlotDensityDoc = md`[#](#densityPlotDensityDoc) *densityPlot*.**density**([_density_]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nIf *density* is specified, sets the [density estimator](#densityEstimationHeader) and returns this plot generator. If *size* is not specified, returns the current density estimator.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":137,"value":"densityPlotSizeDoc = md`[#](#densityPlotSizeDoc) *densityPlot*.**size**([_size_]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nIf *size* is specified, sets the size of the plot canvas, not including the additional space for axes, and returns this plot generator. If *size* is not specified, returns the current size, which defaults to \\`[xBins, yBins]\\` from the underlying density estimator.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":165,"value":"densityPlotColorDoc = md`[#](#densityPlotColorDoc) *densityPlot*.**color**([_color_]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nIf *color* is specified, sets the color accessor and returns this plot generator. The color accessor is a function that accepts the computed density array as an argument and returns a color scale to use for plotting. If *color* is not specified, returns the current color accessor, which defaults to a reverse [Viridis](https://github.com/d3/d3-scale-chromatic#interpolateViridis) color scale.\n\nThe color scale returned by the color accessor may return the color as a \\`String\\` or as an \\`{r, g, b, opacity}\\` object. Returning objects can be more efficient than the color string representation, which has to be parsed into channel components.\n\nThis function will be invoked multiple times if the density estimator returns a generator.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":385,"value":"densityPlotDrawAxesDoc = md`[#](#densityPlotDrawAxesDoc) *densityPlot*.**drawAxes**([_axes_]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nIf *drawAxes* is specified, sets whether or not to add axes to the plot. If *axes* is not specified, returns the current value, which defaults to \\`true\\`.\n\nBy default, the width and height of the canvas will be adjusted so that *densityPlot*.*size* determines the total size of the chart including axes. If you want the size to determine the canvas size only, pass \\`{ preserveCanvasSize: true }\\` as the value of *axes*.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":913,"value":"densityPlotXAxisScaleDoc = md`[#](#densityPlotXAxisScaleDoc) *densityPlot*.**xAxisScale**([_scale_]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nIf *xAxisScale* is specified, overrides the default x axis display with one that uses the domain of the given color scale. If *xAxisScale* is not specified, returns the current value, which defaults to \\`null\\`.\n\nOnly the domain from the scale will be used, as the range is determined by the plot size. For example, to use a time axis:\n\n\\`\\`\\`\ndensityPlot.xAxisScale(d3.scaleTime().domain([startTime, endTime]))\n\\`\\`\\`\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":922,"value":"densityPlotYAxisScaleDoc = md`[#](#densityPlotYAxisScaleDoc) *densityPlot*.**yAxisScale**([_scale_]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nIf *yAxisScale* is specified, overrides the default y axis display with one that uses the domain of the given color scale. If *yAxisScale* is not specified, returns the current value, which defaults to \\`null\\`.\n\nOnly the domain from the scale will be used, as the range is determined by the plot size.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":928,"value":"densityPlotBackgroundDoc = md`[#](#densityPlotBackgroundDoc) *densityPlot*.**background**([_color_]) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nIf *color* is specified, overrides the color used for density bins with zero weight. By default the color is computed from the color scale but it is sometimes useful to colorize bins with no data separately. If *color* is not specified, returns the current value, which defaults to \\`null\\`.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":895,"value":"densityPlotCallDoc = md`[#](#densityPlotDoc) **densityPlot**(_data_) [<>](https://observablehq.com/@twitter/density-plots#densityPlot)\n\nCreate and return a visualization of the density plot for the given data, which can be an array or any iterable.\n\nThe \\`value\\` of the returned DOM node will be a \\`{ canvas, colorScale, buffers, density, update }\\` object. \n\nThe returned canvas element and color scale are \\`canvas\\` and \\`colorScale\\`, respectively, while \\`buffers\\` is an array containing the underlying density buffer(s) for this plot, \\`density\\` is the copy of the density estimator used for this specific chart, and \\`update\\` is a function to re-render the chart with new data. The update function currently works only for charts that do not use batched rendering.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":497,"value":"md`---`","pinned":false,"hidden":false,"mode":"ojs"},{"id":119,"value":"densityEstimationHeader = md`\n## Density Estimators\n\nThis library provides two bin-based density estimation methods, one for points and another for time series. Each one is a configurable function that takes a dataset and computes a 2d histogram of density values.\n\nThe buffers returned by density estimators represent data in column-major order.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":585,"value":"pointDensityTitle = md`### Point Density\n\nUse \\`pointDensity\\` to compute density data for scatterplots. Each datum is treated as an ${tex`(x, y)`} point and projected to a single bin.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":210,"value":"pointDensityDoc = md`[#](#pointDensityDoc) **pointDensity**([*xBins*, *yBins*]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nConstructs a new density estimator with default settings. If *xBins* and *yBins* are specified, sets the number of horizontal and vertical bins.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":219,"value":"pointDensityXBinsDoc = md`[#](#pointDensityXBinsDoc) *pointDensity*.**xBins**([_xBins_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *xBins* is specified, sets the number of horizontal bins to use for estimation and returns this density estimator. If *xBins* is not specified, returns the current number of horizontal bins.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":224,"value":"pointDensityYBinsDoc = md`[#](#pointDensityYBinsDoc) *pointDensity*.**yBins**([_yBins_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *yBins* is specified, sets the number of vertical bins to use for estimation and returns this density estimator. If *yBins* is not specified, returns the current number of vertical bins.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":230,"value":"pointDensityXDoc = md`[#](#pointDensityXDoc) *pointDensity*.**x**([_x_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *x* is specified, sets the x accessor to the specified function and returns this density estimator. If *x* is not specified, returns the current x accessor, which defaults to:\n\n~~~js\nfunction x(d) {\n return d[0];\n}\n~~~\n\nWhen density is estimated, the x accessor will be invoked for each element in the input data array, being passed the element \\`d\\`, the index \\`i\\`, and the array \\`data\\` as three arguments. The default x accessor assumes that the input data are two-element arrays of numbers. If your data are in a different format, or if you wish to transform the data before rendering, then you should specify a custom accessor.\n\nData points with a \\`NaN\\` x value are ignored.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":243,"value":"pointDensityYDoc = md`[#](#pointDensityYDoc) *pointDensity*.**y**([_y_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *y* is specified, sets the y accessor to the specified function and returns this density estimator. If *y* is not specified, returns the current y accessor, which defaults to:\n\n~~~js\nfunction y(d) {\n return d[1];\n}\n~~~\n\nWhen density is estimated, the y accessor will be invoked for each element in the input data array, being passed the element \\`d\\`, the index \\`i\\`, and the array \\`data\\` as three arguments. See [*pointDensity*.x](#pointDensityXDoc) for more information.\n\nData points with a \\`NaN\\` y value are ignored.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":263,"value":"pointDensityXDomainDoc = md`[#](#pointDensityXDomainDoc) *pointDensity*.**xDomain**([_xDomain_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *xDomain* is specified, sets the x domain to the specified array and returns this density estimator. If *xDomain* is not specified, returns the current x domain. \n\nThe x domain is defined as an array \\`[min, max]\\` where \\`min\\` is the minimum observable value and \\`max\\` is the maximum observable value; both values are inclusive. Any value outside of this domain will be ignored when bins are computed and density is estimated.\n\nIt is recommended to specify the x domain. Not doing so incurs a performance cost, as the data iterator will need to be traversed to compute it.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":264,"value":"pointDensityYDomainDoc = md`[#](#pointDensityYDomainDoc) *pointDensity*.**yDomain**([_yDomain_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *yDomain* is specified, sets the y domain to the specified array and returns this density estimator. If *yDomain* is not specified, returns the current y domain. \n\nThe y domain is defined as an array \\`[min, max]\\` where \\`min\\` is the minimum observable value and \\`max\\` is the maximum observable value; both values are inclusive. Any value outside of this domain will be ignored when bins are computed and density is estimated.\n\nIt is recommended to specify the y domain. Not doing so incurs a performance cost, as the data iterator will need to be traversed to compute it.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":945,"value":"pointDensityWeightDoc = md`[#](#pointDensityWeightDoc) *pointDensity*.**weight**([_weight_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *weight* is specified, sets the weight function to the specified value and returns this density estimator. If *weight* is not specified, returns the current weight function, which defaults to \\`d => 1\\`.\n\nThe weight function is called for every data point when accumulating density into the density buffer and is used to specify the density contribution of each data point. By default, all points are of equal weight.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":938,"value":"pointDensityReduceOpDoc = md`[#](#pointDensityReduceOpDoc) *pointDensity*.**reduceOp**([_op_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *op* is specified, sets the reduction operation to the specified value and returns this density estimator. If *op* is not specified, returns the current reduction operation, which defaults to \\`(x, y) => x + y\\`.\n\nThe reduction operation is used when accumulating weight from data points into the density buffer. The new value for a bin is \\`op(currentValue, dataPointWeight)\\`. The default operation is addition, meaning that density accumulates linearly as points are plotted into a density bin.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":340,"value":"pointDensityBatchSizeDoc = md`[#](#pointDensityBatchSizeDoc) *pointDensity*.**batchSize**([_size_]) [<>](https://observablehq.com/@twitter/density-plots#pointDensity)\n\nIf *size* is specified, sets the batch size to the specified value and returns this density estimator. If *size* is not specified, returns the current batch size, which defaults to \\`null\\`.\n\nIf *size* is \\`null\\`, density estimation returns an array. If *size* is a positive integer, density estimation returns a generator which yields a partial density estimate every *size* data points.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":588,"value":"seriesDensityDoc = md`### Series Density\n\nUse \\`seriesDensity\\` to compute density data for line charts. Each datum is treated as a uniformly sampled series and is projected to a piecewise linear curve. \n\nIn order to avoid misleading the viewer, a normalization is applied so that each line contributes an equal amount of density regardless of its arc length. See the paper [\"Visualizing a Million Time Series with\nthe Density Line Chart\"](https://idl.cs.washington.edu/files/2018-DenseLines-arXiv.pdf) for details.\n\nAll of the methods of *seriesDensity* are the same other than the removal of *x* and *y* accessors, and the addition of *x0* and *ys* accessors for the initial offset of a series and its y values.\n\nWhen the number of \"time\" values exceeds the number of x bins, it may make more sense to plot ${tex`(t, y)`} as points.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":879,"value":"seriesDensityConstructorDoc = md`[#](#seriesDensityDoc) **seriesDensity**([*xBins*, *yBins*]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nConstructs a new density estimator with default settings. If *xBins* and *yBins* are specified, sets the number of horizontal and vertical bins.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":787,"value":"seriesDensityXBinsDoc = md`[#](#seriesDensityXBinsDoc) *seriesDensity*.**xBins**([_xBins_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *xBins* is specified, sets the number of horizontal bins to use for estimation and returns this density estimator. If *xBins* is not specified, returns the current number of horizontal bins.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":791,"value":"seriesDensityYBinsDoc = md`[#](#seriesDensityYBinsDoc) *seriesDensity*.**yBins**([_yBins_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *yBins* is specified, sets the number of vertical bins to use for estimation and returns this density estimator. If *yBins* is not specified, returns the current number of vertical bins.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":793,"value":"seriesDensityX0Doc = md`[#](#seriesDensityX0Doc) *seriesDensity*.**x0**([_x0_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *x0* is specified, sets the x offset accessor to the specified function and returns this density estimator. If *x0* is not specified, returns the current series offset accessor, which defaults to:\n\n~~~js\nfunction x0(d) {\n return d.x0 || 0;\n}\n~~~\n\nWhen density is estimated, the x accessor will be invoked for each element in the input data array, being passed the element \\`d\\`, the index \\`i\\`, and the array \\`data\\` as three arguments.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":795,"value":"seriesDensityYsDoc = md`[#](#seriesDensityYsDoc) *seriesDensity*.**ys**([_ys_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *ys* is specified, sets the y values accessor to the specified function and returns this density estimator. If *ys* is not specified, returns the current y values accessor, which defaults to:\n\n~~~js\nfunction ys(d) {\n return d;\n}\n~~~\n\nWhen density is estimated, the y values accessor will be invoked for each element (series) in the input data array, being passed the element \\`d\\`, the index \\`i\\`, and the array \\`data\\` as three arguments.\n\nThe y values for a given series are expected to be array-like: they should be indexable (\\`ys[n]\\`) and define \\`ys.length\\`. Individual line segments whose endpoints contain a \\`NaN\\` value are ignored.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":799,"value":"seriesDensityXDomainDoc = md`[#](#seriesDensityXDomainDoc) *seriesDensity*.**xDomain**([_xDomain_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *xDomain* is specified, sets the x domain to the specified array and returns this density estimator. If *xDomain* is not specified, returns the current x domain. \n\nThe x domain is defined as an array \\`[min, max]\\` where \\`min\\` is the minimum observable value and \\`max\\` is the maximum observable value; both values are inclusive. Any value outside of this domain will be ignored when bins are computed and density is estimated.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":802,"value":"seriesDensityYDomainDoc = md`[#](#seriesDensityYDomainDoc) *seriesDensity*.**yDomain**([_yDomain_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *yDomain* is specified, sets the y domain to the specified array and returns this density estimator. If *yDomain* is not specified, returns the current y domain. \n\nThe y domain is defined as an array \\`[min, max]\\` where \\`min\\` is the minimum observable value and \\`max\\` is the maximum observable value; both values are inclusive. Any value outside of this domain will be ignored when bins are computed and density is estimated.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":805,"value":"seriesDensityBatchSizeDoc = md`[#](#seriesDensityBatchSizeDoc) *seriesDensity*.**batchSize**([_size_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *size* is specified, sets the batch size to the specified value and returns this density estimator. If *size* is not specified, returns the current batch size, which defaults to \\`null\\`.\n\nIf *size* is \\`null\\`, density estimation returns an array. If *size* is a positive integer, density estimation returns a generator which yields a partial density estimate every *size* series.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":906,"value":"seriesDensityArcLengthNormalizeDoc = md`[#](#seriesDensityYBinsDoc) *seriesDensity*.**arcLengthNormalize**([_yBins_]) [<>](https://observablehq.com/@twitter/density-plots#seriesDensity)\n\nIf *arcLengthNormalize* is specified, sets whether to perform [arc-length normalization](https://arxiv.org/pdf/1808.06019v1.pdf) and returns this density estimator. If *arcLengthNormalize* is not specified, returns the current value of this parameter, which defaults to \\`true\\`.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1087,"value":"convenienceFunctionsTitle = md`## Convenience functions`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1056,"value":"cacheInterpolatorDoc = md`[#](#densityPlotDoc) **cacheInterpolator**(*interpolator*, [*n=250*]) [<>](https://observablehq.com/@twitter/density-plots#cacheInterpolator)\n\nThis is a convenience function for creating a quantized color interpolator that returns cached \\`{r, g, b, opacity}\\` objects. The parameter *n* specifies the number of samples.\n\nUsing a cached interpolator with density plots is more efficient than using an interpolator returning color strings since it avoids the performance cost of parsing color strings while rendering.\n\nInterpolators returned by \\`cacheInterpolator\\` can be passed directly to a [sequential](https://observablehq.com/@d3/sequential-scales) or [diverging](https://observablehq.com/@d3/diverging-scales) color scale.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":763,"value":"support = md`## Support\n\nTo report bugs or get support with library usage, you can leave a comment on this notebook, email [yurivish@gmail.com](Yuri Vishnevsky), or contact Twitter Open Source at [@TwitterOSS](https://twitter.com/twitteross).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":757,"value":"changelog = md`\n## Changelog\n* \\`v4159\\`: fixed an axis bug in \\`densityPlot\\`\n* \\`v4155\\`: initial release.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":749,"value":"security = md`\n## Security Issues?\nPlease report sensitive security issues via Twitter's bug-bounty program (https://hackerone.com/twitter) rather than GitHub.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":589,"value":"md`---`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2,"value":"import {\n densityPlot,\n pointDensity,\n seriesDensity,\n importStatement\n} from '@twitter/density-plot@4159'","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}