diff --git a/docs/community.md b/docs/community.md index 7ff2f5ced7..af5e1cba01 100644 --- a/docs/community.md +++ b/docs/community.md @@ -14,7 +14,7 @@ And of course, follow us on [Observable](https://observablehq.com/@observablehq? We recommend asking for help on the [Observable forum](https://talk.observablehq.com/c/help/6). Or if you prefer chat, join the [Observable community Slack](https://observable-community.slack.com/ssb/redirect). -We encourage you to share your work, no matter how messy, on [Observable](https://observablehq.com). Sharing live code is the easiest way to let people see what you see, and to debug your problem. Strive for a [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)—it helps people hone in on your problem more quickly. +We encourage you to share your work, no matter how messy, on [Observable](https://observablehq.com). Sharing live code is the easiest way to let people see what you see, and to debug your problem. Strive for a [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) — it helps people hone in on your problem more quickly. When asking for help, don’t just post your code and ask people to fix it. Provide context, and say what you want help with. For example: @@ -23,7 +23,7 @@ When asking for help, don’t just post your code and ask people to fix it. Prov - What behavior are you currently seeing? - Is the current behavior not what you expect? -If you think you’ve found a bug in Plot, please file a [GitHub issue](https://github.com/observablehq/plot/issues). But don’t use an issue to ask for help—you’ll have better luck on the forum or Slack. +If you think you’ve found a bug in Plot, please file a [GitHub issue](https://github.com/observablehq/plot/issues). But don’t use an issue to ask for help — you’ll have better luck on the forum or Slack. ## Getting involved diff --git a/docs/features/marks.md b/docs/features/marks.md index e7819609de..63b6265c85 100644 --- a/docs/features/marks.md +++ b/docs/features/marks.md @@ -58,7 +58,7 @@ Plot doesn’t have chart types; instead, you construct charts by layering **mar ## Marks are geometric shapes -Plot provides a variety of mark types. Think of marks as the “visual vocabulary”—the painter’s palette 🎨, but of shapes instead of colors—that you pull from when composing a chart. Each mark type produces a certain type of geometric shape. +Plot provides a variety of mark types. Think of marks as the “visual vocabulary” — the painter’s palette 🎨, but of shapes instead of colors — that you pull from when composing a chart. Each mark type produces a certain type of geometric shape. For example, the [dot mark](../marks/dot.md) draws stroked circles (by default). @@ -157,7 +157,7 @@ Plot.plot({ ## Marks use scales -Marks are (typically) not positioned in literal pixels, or colored in literal colors, as in a conventional graphics system. Instead you provide abstract values such as time and temperature—marks are drawn “in data space”—and [scales](./scales.md) encode these into visual values such as position and color. And best of all, Plot automatically creates [axes](../marks/axis.md) and [legends](./legends.md) to document the scales’ encodings. +Marks are (typically) not positioned in literal pixels, or colored in literal colors, as in a conventional graphics system. Instead you provide abstract values such as time and temperature — marks are drawn “in data space” — and [scales](./scales.md) encode these into visual values such as position and color. And best of all, Plot automatically creates [axes](../marks/axis.md) and [legends](./legends.md) to document the scales’ encodings. Data is passed through scales automatically during rendering; the mark controls which scales are used. The **x** and **y** options are typically bound to the *x* and *y* scales, respectively, while the **fill** and **stroke** options are typically bound to the *color* scale. Changing a scale’s definition, say by overriding its **domain** (the extent of abstract input values) or **type**, affects the appearance of all marks that use the scale. @@ -178,7 +178,7 @@ Plot.plot({ ## Marks have tidy data -A single mark can draw multiple shapes. A mark generally produces a shape—such as a rectangle or circle—for each element in the data. +A single mark can draw multiple shapes. A mark generally produces a shape — such as a rectangle or circle — for each element in the data. :::plot defer https://observablehq.com/@observablehq/plot-tidy-data ```js @@ -194,7 +194,7 @@ Plot.lineY(aapl, {x: "Date", y: "Close"}).plot() ``` ::: -And a line mark isn’t even guaranteed to produce a single polyline—there can be multiple polylines, as in a line chart with multiple series (using **z**). +And a line mark isn’t even guaranteed to produce a single polyline — there can be multiple polylines, as in a line chart with multiple series (using **z**). :::plot defer https://observablehq.com/@observablehq/plot-multiple-series-line-chart ```js @@ -258,10 +258,10 @@ Note that when accessor functions or parallel arrays are used instead of field n Data comes in different types: quantitative (or temporal) values can be subtracted, ordinal values can be ordered, and nominal (or categorical) values can only be the same or different. :::info -Because nominal values often need some arbitrary order for display purposes—often alphabetical—Plot uses the term *ordinal* to refer to both ordinal and nominal data. +Because nominal values often need some arbitrary order for display purposes — often alphabetical — Plot uses the term *ordinal* to refer to both ordinal and nominal data. ::: -Some marks work with any type of data, while other marks have certain requirements or assumptions of data. For example, a line should only be used when both *x* and *y* are quantitative or temporal, and when the data is in a meaningful order (such as chronological). This is because the line mark will interpolate between adjacent points to draw line segments. If *x* or *y* is nominal—say the names of countries—it doesn’t make sense to use a line because there is no half-way point between two nominal values. +Some marks work with any type of data, while other marks have certain requirements or assumptions of data. For example, a line should only be used when both *x* and *y* are quantitative or temporal, and when the data is in a meaningful order (such as chronological). This is because the line mark will interpolate between adjacent points to draw line segments. If *x* or *y* is nominal — say the names of countries — it doesn’t make sense to use a line because there is no half-way point between two nominal values. :::plot https://observablehq.com/@observablehq/plot-dont-do-this ```js @@ -357,7 +357,7 @@ Channels are mark options that can be used to encode data. These options allow t * an accessor function, or * an array of values of the same length and order as the data. -Not all mark options can be expressed as channels. For example, **stroke** can be a channel but **strokeDasharray** cannot. This is mostly a pragmatic limitation—it would be harder to implement Plot if every option were expressible as a channel—but it also serves to guide you towards options that are intended for encoding data. +Not all mark options can be expressed as channels. For example, **stroke** can be a channel but **strokeDasharray** cannot. This is mostly a pragmatic limitation — it would be harder to implement Plot if every option were expressible as a channel — but it also serves to guide you towards options that are intended for encoding data. :::tip To vary the definition of a constant option with data, create multiple marks with your different constant options, and then filter the data for each mark to achieve the desired result. diff --git a/docs/features/projections.md b/docs/features/projections.md index e34168d98d..0035809f00 100644 --- a/docs/features/projections.md +++ b/docs/features/projections.md @@ -56,7 +56,7 @@ Plot.plot({ Above, a [geo mark](../marks/geo.md) draws polygons representing land and a [sphere mark](../marks/geo.md#sphere-options) draws the outline of the globe. A [dot mark](../marks/dot.md) draws earthquakes as circles sized by magnitude. -The geo mark is “projection aware” so that it can handle all the nuances of projecting spherical polygons to the screen—leaning on [d3-geo](https://d3js.org/d3-geo) to provide [adaptive sampling](https://observablehq.com/@d3/adaptive-sampling) with configurable precision, [antimeridian cutting](https://observablehq.com/@d3/antimeridian-cutting), and clipping. The dot mark is not; instead, Plot applies the projection in place of the *x* and *y* scales. Hence, projections work with any mark that consumes continuous **x** and **y** channels—as well as marks that use **x1** & **y1** and **x2** & **y2**. Each mark implementation decides whether to handle projections specially or to treat the projection as any other position scale. (For example, the [line mark](../marks/line.md) is projection-aware to draw geodesics.) +The geo mark is “projection aware” so that it can handle all the nuances of projecting spherical polygons to the screen — leaning on [d3-geo](https://d3js.org/d3-geo) to provide [adaptive sampling](https://observablehq.com/@d3/adaptive-sampling) with configurable precision, [antimeridian cutting](https://observablehq.com/@d3/antimeridian-cutting), and clipping. The dot mark is not; instead, Plot applies the projection in place of the *x* and *y* scales. Hence, projections work with any mark that consumes continuous **x** and **y** channels — as well as marks that use **x1** & **y1** and **x2** & **y2**. Each mark implementation decides whether to handle projections specially or to treat the projection as any other position scale. (For example, the [line mark](../marks/line.md) is projection-aware to draw geodesics.) :::info Marks that require *band* scales (bars, cells, and ticks) cannot be used with projections. Likewise one-dimensional marks such as rules cannot be used, though see [#1164](https://github.com/observablehq/plot/issues/1164). diff --git a/docs/features/scales.md b/docs/features/scales.md index 8516599124..36376e1d76 100644 --- a/docs/features/scales.md +++ b/docs/features/scales.md @@ -76,7 +76,7 @@ Plot.ruleX(gistemp, {x: "Date", stroke: "Anomaly"}).plot() ``` ::: -While the resulting chart looks different, the *color* scale here behaves similarly to the `y` function above—the only difference is that it interpolates colors (using [d3.interpolateTurbo](https://d3js.org/d3-scale-chromatic/sequential#interpolateTurbo)) instead of numbers (the top and bottom sides of the plot frame): +While the resulting chart looks different, the *color* scale here behaves similarly to the `y` function above — the only difference is that it interpolates colors (using [d3.interpolateTurbo](https://d3js.org/d3-scale-chromatic/sequential#interpolateTurbo)) instead of numbers (the top and bottom sides of the plot frame): ```js function color(anomaly) { @@ -163,7 +163,7 @@ Plot.plot({x: {type: "utc", domain: [1609459200000, 1640995200000], grid: true}} ``` ::: -If the scale **type** is *time*, the ticks will be in local time—as with the dates below—rather than UTC. +If the scale **type** is *time*, the ticks will be in local time — as with the dates below — rather than UTC. :::plot https://observablehq.com/@observablehq/plot-continuous-scales ```js @@ -241,7 +241,7 @@ Plot ``` ::: -While *point* and *band* scales appear visually similar when only the grid is visible, the two are not identical—they differ respective to padding. Play with the options below to get a sense of their effect on the scale’s behavior. +While *point* and *band* scales appear visually similar when only the grid is visible, the two are not identical — they differ respective to padding. Play with the options below to get a sense of their effect on the scale’s behavior.