diff --git a/CHANGELOG.md b/CHANGELOG.md index cdb3a0b6e9..e7de2c7826 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,88 @@ Year: **Current (2023)** · [2022](./CHANGELOG-2022.md) · [2021](./CHANGELOG-2021.md) +## 0.6.10 + +[Released August 14, 2023.](https://github.com/observablehq/plot/releases/tag/v0.6.10) + +The new **title** and **subtitle** [plot options](https://observablehq.com/plot/features/plots#other-options) specify a primary and secondary heading. Headings are implemented as h2 and h3 elements by default, but you can provide existing elements instead of text for greater control. Like the existing **caption** option, headings add context and assist interpretation. + +A chart with a title, subtitle, and caption. + +```js +Plot.plot({ + title: "For charts, an informative title", + subtitle: "Subtitle to follow with additional context", + caption: "Figure 1. A chart with a title, subtitle, and caption.", + marks: [ + Plot.frame(), + Plot.text(["Titles, subtitles, captions, and annotations assist inter­pretation by telling the reader what’s interesting. Don’t make the reader work to find what you already know."], {lineWidth: 30, frameAnchor: "middle"}) + ] +}) +``` + +When a chart has a title, subtitle, caption, or legend, Plot automatically wraps the chart’s SVG element with an HTML figure element. The new **figure** plot option, if true, wraps the chart in a figure even if it doesn’t have these other elements; likewise, if false, Plot ignores these other elements and returns a bare SVG element. The figure element now has an associated class (`plot-d6a7b5-figure`). + +The new **clip** plot option determines the default clipping behavior if the [**clip** mark option](https://observablehq.com/plot/features/marks#mark-options) is not specified; set it to true to enable clipping. This option does not affect axis, grid, and frame marks, whose **clip** option defaults to false. + +A line chart of the AAPL ticker, clipped to the frame. + +```js +Plot.plot({ + clip: true, + x: {domain: [new Date(2015, 0, 1), new Date(2015, 3, 1)]}, + y: {grid: true}, + marks: [ + Plot.areaY(aapl, {x: "Date", y: "Close", fillOpacity: 0.1}), + Plot.lineY(aapl, {x: "Date", y: "Close"}), + Plot.ruleY([0], {clip: false}) + ] +}); +``` + +The new [bollinger mark](https://observablehq.com/plot/marks/bollinger) composes a line representing a moving average and an area representing volatility as a band; the band thickness is proportional to the deviation of nearby values. The bollinger mark is built on the new [bollinger map method](https://observablehq.com/plot/marks/bollinger#bollinger), and is often used to analyze the price of financial instruments such as stocks. + +A bollinger chart of the AAPL ticker, computed on a window of the 20 most recent values and a bandwidth of 2 standard deviations. + +```js +Plot.bollingerY(aapl, {x: "Date", y: "Close", n: 20, k: 2}).plot() +``` + +The [arrow mark](https://observablehq.com/plot/marks/arrow) supports a new **sweep** option to control the bend orientation. Below, we set this option to *-y* to draw arrows bulging right, independent of the relative vertical positions of its source and target. + +[Detail of an arc diagram connecting characters in Les Misérables that appear in the same chapters.](https://observablehq.com/@observablehq/plot-arc-diagram?intent=fork) + +```js +Plot.plot({ + height: 1080, + marginLeft: 100, + axis: null, + x: {domain: [0, 1]}, // see https://github.com/observablehq/plot/issues/1541 + color: {domain: d3.range(10), unknown: "#ccc"}, + marks: [ + Plot.dot(miserables.nodes, {x: 0, y: "id", fill: "group", sort: {y: "fill"}}), + Plot.text(miserables.nodes, {x: 0, y: "id", text: "id", textAnchor: "end", dx: -6, fill: "group"}), + Plot.arrow(miserables.links, {x: 0, y1: "source", y2: "target", sweep: "-y", bend: 90, headLength: 0, stroke: samegroup, sort: samegroup, reverse: true}) + ] +}) +``` + +The [auto mark](https://observablehq.com/plot/marks/auto) now does a better job determining the appropriate bar mark implementation, such as with ordinal time series bar charts. + +A stacked bar chart from a time series. + +```js +Plot.auto(timeSeries, {x: "date", y: {value: "value", reduce: "sum"}, color: "type", mark: "bar"}).plot() +``` + +The [pointerX and pointerY transform](https://observablehq.com/plot/interactions/pointer) now use unscaled distance to decide the closest point across facets, preventing points from distant facets from being considered closest. The pointer transform now correctly reports the closest point when moving between facets, and no longer reports multiple closest points if they are the same distance across facets. + +Plot’s documentation now has an [API index](https://observablehq.com/plot/api), version badges pointing to the release notes for a particular feature (or to the pull request for a prerelease feature), and shorter anchors. + +The [tip mark](https://observablehq.com/plot/marks/tip) now shows both labels for paired channels such as *y1*–*y2* or *x1*–*y2* when the channel labels differ. When the **tip** option is set to true on a [geo mark](https://observablehq.com/plot/marks/geo) without a projection, as when using preprojected planar geometry, the display no longer collapses. + +The [stack transform](https://observablehq.com/plot/transforms/stack) now emits a friendlier error message when the supplied value is null. + ## 0.6.9 [Released June 27, 2023.](https://github.com/observablehq/plot/releases/tag/v0.6.9) diff --git a/docs/features/plots.md b/docs/features/plots.md index 88b79ff5ac..13351e4241 100644 --- a/docs/features/plots.md +++ b/docs/features/plots.md @@ -248,9 +248,9 @@ When using facets, set the *fx* and *fy* scales’ **round** option to false if ## Other options -By default, [plot](#plot) returns an SVG element; however, if the plot includes a title, subtitle, [legend](./legends.md), or caption, plot wraps the SVG element with an HTML figure element. You can also force Plot to generate a figure element by setting the **figure** option to true. +By default, [plot](#plot) returns an SVG element; however, if the plot includes a title, subtitle, [legend](./legends.md), or caption, plot wraps the SVG element with an HTML figure element. You can also force Plot to generate a figure element by setting the **figure** option to true. -The **title** & **subtitle** options and the **caption** option accept either a string or an HTML element. If given an HTML element, say using the [`html` tagged template literal](http://github.com/observablehq/htl), the title and subtitle are used as-is while the caption is wrapped in a figcaption element; otherwise, the specified text will be escaped and wrapped in an h2, h3, or figcaption, respectively. +The **title** & **subtitle** options and the **caption** option accept either a string or an HTML element. If given an HTML element, say using the [`html` tagged template literal](http://github.com/observablehq/htl), the title and subtitle are used as-is while the caption is wrapped in a figcaption element; otherwise, the specified text will be escaped and wrapped in an h2, h3, or figcaption, respectively. :::plot https://observablehq.com/@observablehq/plot-caption ```js @@ -274,7 +274,7 @@ Unitless numbers ([quirky lengths](https://www.w3.org/TR/css-values-4/#deprecate The generated SVG element has a class name which applies a default stylesheet. Use the top-level **className** option to specify that class name. -The **clip** option determines the default clipping behavior if the [mark **clip** option](./marks.md#mark-options) is not specified; set it to true to enable clipping. This option does not affect [axis](../marks/axis.md), [grid](../marks/grid.md), and [frame](../marks/frame.md) marks, whose **clip** option defaults to false. +The **clip** option determines the default clipping behavior if the [mark **clip** option](./marks.md#mark-options) is not specified; set it to true to enable clipping. This option does not affect [axis](../marks/axis.md), [grid](../marks/grid.md), and [frame](../marks/frame.md) marks, whose **clip** option defaults to false. The **document** option specifies the [document](https://developer.mozilla.org/en-US/docs/Web/API/Document) used to create plot elements. It defaults to window.document, but can be changed to another document, say when using a virtual DOM implementation for server-side rendering in Node. diff --git a/docs/marks/arrow.md b/docs/marks/arrow.md index d34ce3e90a..0c94fa4762 100644 --- a/docs/marks/arrow.md +++ b/docs/marks/arrow.md @@ -146,7 +146,7 @@ The arrow mark supports the [standard mark options](../features/marks.md#mark-op The **bend** option sets the angle between the straight line connecting the two points and the outgoing direction of the arrow from the start point. It must be within ±90°. A positive angle will produce a clockwise curve; a negative angle will produce a counterclockwise curve; zero will produce a straight line. The **headAngle** determines how pointy the arrowhead is; it is typically between 0° and 180°. The **headLength** determines the scale of the arrowhead relative to the stroke width. Assuming the default of stroke width 1.5px, the **headLength** is the length of the arrowhead’s side in pixels. -The **sweep** option controls the bend orientation. It defaults to 1 indicating a positive (clockwise) bend angle; -1 indicates a negative (anticlockwise) bend angle; 0 effectively clears the bend angle. If *-x*, the bend angle is flipped when the ending point is to the left of the starting point — ensuring all arrows bulge up (down if bend is negative); if *-y*, the bend angle is flipped when the ending point is above the starting point — ensuring all arrows bulge right (left if bend is negative); the sign is negated for *+x* and *+y*. +The **sweep** option controls the bend orientation. It defaults to 1 indicating a positive (clockwise) bend angle; -1 indicates a negative (anticlockwise) bend angle; 0 effectively clears the bend angle. If *-x*, the bend angle is flipped when the ending point is to the left of the starting point — ensuring all arrows bulge up (down if bend is negative); if *-y*, the bend angle is flipped when the ending point is above the starting point — ensuring all arrows bulge right (left if bend is negative); the sign is negated for *+x* and *+y*. ## arrow(*data*, *options*) {#arrow} diff --git a/docs/marks/bollinger.md b/docs/marks/bollinger.md index 6ebd8f9ded..949ba8cb44 100644 --- a/docs/marks/bollinger.md +++ b/docs/marks/bollinger.md @@ -10,7 +10,7 @@ const k = ref(2); -# Bollinger mark +# Bollinger mark The **bollinger mark** is a [composite mark](../features/marks.md#marks) consisting of a [line](./line.md) representing a moving average and an [area](./area.md) representing volatility as a band; the band thickness is proportional to the deviation of nearby values. The bollinger mark is often used to analyze the price of financial instruments such as stocks. diff --git a/img/arc-diagram.png b/img/arc-diagram.png new file mode 100644 index 0000000000..d078000eea Binary files /dev/null and b/img/arc-diagram.png differ diff --git a/img/auto-bar.png b/img/auto-bar.png new file mode 100644 index 0000000000..7709798871 Binary files /dev/null and b/img/auto-bar.png differ diff --git a/img/bollinger.png b/img/bollinger.png new file mode 100644 index 0000000000..7782daf54b Binary files /dev/null and b/img/bollinger.png differ diff --git a/img/clip.png b/img/clip.png new file mode 100644 index 0000000000..8bc61834fd Binary files /dev/null and b/img/clip.png differ diff --git a/img/title-subtitle.png b/img/title-subtitle.png new file mode 100644 index 0000000000..40a307a6ad Binary files /dev/null and b/img/title-subtitle.png differ diff --git a/package.json b/package.json index dfe00e8c23..f42de6b215 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@observablehq/plot", "description": "A JavaScript library for exploratory data visualization.", - "version": "0.6.9", + "version": "0.6.10", "author": { "name": "Observable, Inc.", "url": "https://observablehq.com"