diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e1a3d5790..27b971440d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -228,7 +228,7 @@ TypeScript also helps for reading code; hover any symbol and immediately see the Lastly, if you’re using Plot in a TypeScript project, you can now benefit from additional static type checking to find errors. -A screenshot of VS Code, showing an red squiggly underline under a typo in the code, which accidentally calls mark.plots. A panel suggests calling mark.plot instead. +A screenshot of VS Code, showing a red squiggly underline under a typo in the code, which accidentally calls mark.plots. A panel suggests calling mark.plot instead. If you have suggestions or clarifications on how to improve the documentation, please open an issue or discussion, or send us a pull request. diff --git a/docs/features/facets.md b/docs/features/facets.md index 3196fae662..a4bf230f69 100644 --- a/docs/features/facets.md +++ b/docs/features/facets.md @@ -92,7 +92,7 @@ Plot.plot({ Here the sort order has changed slightly: the *y* and *fy* domains are sorted by the median **x1** values, which are the yields for 1931. ::: -Faceting requires ordinal or categorical data because there are a discrete number of facets; the associated *fx* and *fy* scales are [band scales](./scales.md#discrete-position). Quantitative or temporal data can be made ordinal by binning, say using [Math.floor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor). Or, use the [**interval** scale option](./scales.md#scale-transforms) on the *fx* or *fy* scale. Below, we produce a [box plot](../marks/box.md) of the weights (in kilograms) of Olympic athletes, faceted by height binned at a 10cm (0.1 meter) interval. +Faceting requires ordinal or categorical data because there are a discrete number of facets; the associated *fx* and *fy* scales are [band scales](./scales.md#discrete-scales). Quantitative or temporal data can be made ordinal by binning, say using [Math.floor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor). Or, use the [**interval** scale option](./scales.md#scale-transforms) on the *fx* or *fy* scale. Below, we produce a [box plot](../marks/box.md) of the weights (in kilograms) of Olympic athletes, faceted by height binned at a 10cm (0.1 meter) interval. :::plot defer https://observablehq.com/@observablehq/plot-olympians-box-plot ```js @@ -299,7 +299,7 @@ With top-level faceting, any mark that uses the specified facet data will be fac ## Facet scales -When faceting, two additional [band scales](./scales.md#discrete-position) may be configured: +When faceting, two additional [band scales](./scales.md#discrete-scales) may be configured: * *fx* - the horizontal↔︎ position, a *band* scale * *fy* - the vertical↕︎ position, a *band* scale diff --git a/docs/features/marks.md b/docs/features/marks.md index 71efe01bad..55042c4edc 100644 --- a/docs/features/marks.md +++ b/docs/features/marks.md @@ -522,7 +522,7 @@ Plot.dot(data, {stroke: {value: "fieldName", scale: "color"}}) The color channels (**fill** and **stroke**) are bound to the *color* scale by default, unless the provided values are all valid CSS color strings or nullish, in which case the values are interpreted literally and unscaled. -In addition to functions of data, arrays, and column names, channel values can be specified as an object with a *transform* method; this transform method is passed the mark’s array of data and must return the corresponding array of channel values. (Whereas a channel value specified as a function is invoked repeatedly for each element in the mark’s data, similar to *array*.map, the transform method is invoked only once being passed the entire array of data.) For example, to pass the mark’s data directly to the **x** channel, equivalent to [Plot.identity](./transforms.md#plotidentity): +In addition to functions of data, arrays, and column names, channel values can be specified as an object with a *transform* method; this transform method is passed the mark’s array of data and must return the corresponding array of channel values. (Whereas a channel value specified as a function is invoked repeatedly for each element in the mark’s data, similar to *array*.map, the transform method is invoked only once being passed the entire array of data.) For example, to pass the mark’s data directly to the **x** channel, equivalent to [Plot.identity](./transforms.md#identity): ```js Plot.dot(numbers, {x: {transform: (data) => data}}) @@ -539,7 +539,7 @@ The rectangular marks ([bar](../marks/bar.md), [cell](../marks/cell.md), [frame] * **rx** - the [*x* radius](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx) for rounded corners * **ry** - the [*y* radius](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry) for rounded corners -Insets are specified in pixels. Corner radii are specified in either pixels or percentages (strings). Both default to zero. Insets are typically used to ensure a one-pixel gap between adjacent bars; note that the [bin transform](../transforms/bin.md) provides default insets, and that the [band scale padding](./scales.md#position-scales) defaults to 0.1, which also provides separation. +Insets are specified in pixels. Corner radii are specified in either pixels or percentages (strings). Both default to zero. Insets are typically used to ensure a one-pixel gap between adjacent bars; note that the [bin transform](../transforms/bin.md) provides default insets, and that the [band scale padding](./scales.md#position-scale-options) defaults to 0.1, which also provides separation. For marks that support the **frameAnchor** option, it may be specified as one of the four sides (*top*, *right*, *bottom*, *left*), one of the four corners (*top-left*, *top-right*, *bottom-right*, *bottom-left*), or the *middle* of the frame. diff --git a/docs/features/plots.md b/docs/features/plots.md index 74ab0e4e6c..0096717885 100644 --- a/docs/features/plots.md +++ b/docs/features/plots.md @@ -212,7 +212,7 @@ Plot.plot({ To assist the explanation, the plot above is drawn with a light gray border. ::: -The default **width** is 640. On Observable, the width can be set to the [standard width](https://github.com/observablehq/stdlib/blob/main/README.md#width) to make responsive plots. The default **height** is chosen automatically based on the plot’s associated scales; for example, if *y* is linear and there is no *fy* scale, it might be 396. The default margins depend on the maximum margins of the plot’s constituent [marks](./plots.md#marks). While most marks default to zero margins (because they are drawn inside the chart area), Plot’s [axis mark](../marks/axis.md) has non-zero default margins. +The default **width** is 640. On Observable, the width can be set to the [standard width](https://github.com/observablehq/stdlib/blob/main/README.md#width) to make responsive plots. The default **height** is chosen automatically based on the plot’s associated scales; for example, if *y* is linear and there is no *fy* scale, it might be 396. The default margins depend on the maximum margins of the plot’s constituent [marks](#marks-option). While most marks default to zero margins (because they are drawn inside the chart area), Plot’s [axis mark](../marks/axis.md) has non-zero default margins. :::tip Plot does not adjust margins automatically to make room for long tick labels. If your *y* axis labels are too long, you can increase the **marginLeft** to make more room. Also consider using a different **tickFormat** for short labels (*e.g.*, `s` for SI prefix notation), or a scale **transform** (say to convert units to millions or billions). @@ -301,7 +301,7 @@ const color = plot.scale("color"); // get the color scale console.log(color.range); // inspect the scale’s range ``` -Returns the [scale object](./scales.md#scale-objects) for the scale with the specified *name* (such as *x* or *color*) on the given *plot*, where *plot* is a rendered plot element returned by [plot](#plot-options). If the associated *plot* has no scale with the given *name*, returns undefined. +Returns the [scale object](./scales.md#scale-options) for the scale with the specified *name* (such as *x* or *color*) on the given *plot*, where *plot* is a rendered plot element returned by [plot](#plot-options). If the associated *plot* has no scale with the given *name*, returns undefined. ## *plot*.legend(*name*, *options*) diff --git a/docs/features/scales.md b/docs/features/scales.md index bf2de31a04..db603bb843 100644 --- a/docs/features/scales.md +++ b/docs/features/scales.md @@ -47,7 +47,7 @@ Plot.lineY(gistemp, {x: "Date", y: "Anomaly"}).plot() ``` ::: -In Plot, the [mark](./marks.md) binds channels to scales; for example, the line’s **x** channel is bound to the *x* scale. The channel name and the scale name are often the same, but not always; for example, an area’s **y1** and **y2** channels are both bound to the *y* scale. (You can opt-out of a scale for a particular channel using [scale overrides](./marks.html#mark-options) if needed.) +In Plot, the [mark](./marks.md) binds channels to scales; for example, the line’s **x** channel is bound to the *x* scale. The channel name and the scale name are often the same, but not always; for example, an area’s **y1** and **y2** channels are both bound to the *y* scale. (You can opt-out of a scale for a particular channel using [scale overrides](./marks.md#mark-options) if needed.) Think of a scale as a function that takes an abstract value and returns the corresponding visual value. For the *y* scale above, that might look like this: @@ -1011,7 +1011,7 @@ Plot.barY(alphabet, {x: "letter", y: "frequency", sort: {x: {value: "y", order: If the input channel is *data*, then the reducer is passed groups of the mark’s data; this is typically used in conjunction with a custom reducer function, as when the built-in single-channel reducers are insufficient. -Note: when the value of the sort option is a string or a function, it is interpreted as a mark [sort transform](../transforms/sort.md). To use both sort options and a mark sort transform, use [Plot.sort](../transforms/sort.md#plotsortcompare-options). +Note: when the value of the sort option is a string or a function, it is interpreted as a mark [sort transform](../transforms/sort.md). To use both sort options and a mark sort transform, use [Plot.sort](../transforms/sort.md#sort-order-options). ## scale(*options*) diff --git a/docs/marks/axis.md b/docs/marks/axis.md index 97ffaa389e..0f9411640c 100644 --- a/docs/marks/axis.md +++ b/docs/marks/axis.md @@ -345,7 +345,7 @@ By default, the *data* for an axis mark are tick values sampled from the associa * **tickSpacing** - the approximate number of pixels between ticks (if **ticks** is not specified) * **interval** - an interval or time interval -Note that when an axis mark is declared explicitly (via the [**marks** plot option](../features/plots.md#marks), as opposed to an implicit axis), the corresponding scale’s *scale*.ticks and *scale*.tickSpacing options are not automatically inherited by the axis mark; however, the *scale*.interval option *is* inherited, as is the *scale*.label option. You can declare multiple axis marks for the same scale with different ticks, and styles, as desired. +Note that when an axis mark is declared explicitly (via the [**marks** plot option](../features/plots.md#marks-option), as opposed to an implicit axis), the corresponding scale’s *scale*.ticks and *scale*.tickSpacing options are not automatically inherited by the axis mark; however, the *scale*.interval option *is* inherited, as is the *scale*.label option. You can declare multiple axis marks for the same scale with different ticks, and styles, as desired. In addition to the [standard mark options](../features/marks.md), the axis mark supports the following options: diff --git a/docs/marks/tree.md b/docs/marks/tree.md index bbe42569dd..7ea61bbce2 100644 --- a/docs/marks/tree.md +++ b/docs/marks/tree.md @@ -126,7 +126,7 @@ Plot.plot({ ``` ::: -The tree mark currently does not inform the default layout; you may find it necessary to set the **height** and **margin** [layout options](../features/plots.md#layout) for readability. +The tree mark currently does not inform the default layout; you may find it necessary to set the **height** and **margin** [layout options](../features/plots.md#layout-options) for readability. ## Tree options diff --git a/docs/transforms/centroid.md b/docs/transforms/centroid.md index 9c8278f5c0..409704c29d 100644 --- a/docs/transforms/centroid.md +++ b/docs/transforms/centroid.md @@ -43,7 +43,7 @@ Plot.voronoi(counties, Plot.centroid()).plot({projection: "albers"}) While the centroid transform computes the centroid of a geometry _after_ projection, the geoCentroid transform computes it _before_ projection, then projects the resulting coordinates. This difference has a few implications, as follows. -As an [initializer](../features/transforms.md#initializers), the centroid transform operates _after_ the geometries have been projected to screen coordinates. The resulting **x** and **y** channels reference the pixel coordinates of the planar centroid of the _projected_ shapes. No assumption is made about the geometries: they can be in any coordinate system, and the returned value is in the frame—as long as the projected geometry returns at least one visible point. +As an [initializer](../features/transforms.md#custom-initializers), the centroid transform operates _after_ the geometries have been projected to screen coordinates. The resulting **x** and **y** channels reference the pixel coordinates of the planar centroid of the _projected_ shapes. No assumption is made about the geometries: they can be in any coordinate system, and the returned value is in the frame—as long as the projected geometry returns at least one visible point. :::plot defer https://observablehq.com/@observablehq/plot-centroid-dot ```js diff --git a/docs/transforms/map.md b/docs/transforms/map.md index 589f6e29f0..c2b6f739a9 100644 --- a/docs/transforms/map.md +++ b/docs/transforms/map.md @@ -47,7 +47,7 @@ Plot.plot({ ``` ::: -The [mapY transform](#map-ymap-options) above is shorthand for applying the given map method to all *y* channels. There’s also a less-common [mapX transform](#mapx-map-options) for *x* channels. +The [mapY transform](#mapy-map-options) above is shorthand for applying the given map method to all *y* channels. There’s also a less-common [mapX transform](#mapx-map-options) for *x* channels. The more explicit [map](#map-outputs-options) transform lets you specify which channels to map, and what map method to use for each channel. Like the [group](./group.md) and [bin](./bin.md) transforms, it takes two arguments: an *outputs* object that describes the output channels to compute, and an *options* object that describes the input channels and additional options. So this: diff --git a/docs/transforms/stack.md b/docs/transforms/stack.md index e947da5633..9350b55834 100644 --- a/docs/transforms/stack.md +++ b/docs/transforms/stack.md @@ -51,7 +51,7 @@ const likert = Likert([ # Stack transform -The **stack transform** comes in two orientations: [stackY](#stackystack-options) replaces **y** with **y1** and **y2** to form vertical↑ stacks grouped on **x**, while [stackX](#stackx-stack-options) replaces **x** with **x1** and **x2** for horizontal→ stacks grouped on **y**. In effect, stacking transforms a *length* into *lower* and *upper* positions: the upper position of each element equals the lower position of the next element in the stack. Stacking makes it easier to perceive a total while still showing its parts. +The **stack transform** comes in two orientations: [stackY](#stacky-stack-options) replaces **y** with **y1** and **y2** to form vertical↑ stacks grouped on **x**, while [stackX](#stackx-stack-options) replaces **x** with **x1** and **x2** for horizontal→ stacks grouped on **y**. In effect, stacking transforms a *length* into *lower* and *upper* positions: the upper position of each element equals the lower position of the next element in the stack. Stacking makes it easier to perceive a total while still showing its parts. For example, below is a stacked area chart of [deaths in the Crimean War](https://en.wikipedia.org/wiki/Florence_Nightingale#Crimean_War)—predominantly from disease—using Florence Nightingale’s data.