From 6b34574d7f9206635a09220bebb0f83b2ff7b81d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Tue, 28 Mar 2023 15:12:06 +0200 Subject: [PATCH 1/3] document line --- src/marks/line.d.ts | 142 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/src/marks/line.d.ts b/src/marks/line.d.ts index c49135c5af..553d3b6af1 100644 --- a/src/marks/line.d.ts +++ b/src/marks/line.d.ts @@ -4,26 +4,168 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js"; import type {MarkerOptions} from "../marker.js"; import type {BinOptions, BinReducer} from "../transforms/bin.js"; +/** Options for the line mark. */ export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOptions { + /** + * The horizontal position channel, typically bound to the *x* scale. + */ x?: ChannelValueSpec; + + /** + * The vertical position channel, typically bound to the *y* scale. + */ y?: ChannelValueSpec; + + /** + * If specified, the **z** channel defines series + */ z?: ChannelValue; } +/** Options for the lineX mark. */ export interface LineXOptions extends LineOptions, BinOptions { + /** + * The vertical position channel, typically bound to the *y* scale. If an + * interval is specified, the *data* is binned according to the interval, + * allowing to show zeroes for empty slots, instead of interpolating between + * defined control points. + */ y?: ChannelValueDenseBinSpec; + + /** + * Reducer for when the **y** channel is binned with an **interval**. For + * example, to create a vertical density plot (count of *y* values binned + * every 0.5): + * + * ```js + * Plot.lineX(data, { y: "value", interval: 0.5, reduce: "count" }) + * ``` + */ reduce?: BinReducer; } +/** Options for the lineY mark. */ export interface LineYOptions extends LineOptions, BinOptions { + /** + * The horizontal position channel, typically bound to the *x* scale. If an + * interval is specified, the *data* is binned according to the interval, + * allowing to show zeroes for empty slots, instead of interpolating between + * defined control points. + */ x?: ChannelValueDenseBinSpec; + + /** + * Reducer for when the **x** channel is binned with an **interval**. For + * example, to create a line chart of the count of records by + * month—showing zeros for empty months: + * + * ```js + * Plot.lineY(records, {x: "Date", interval: "month", reduce: "count"}) + * ``` + */ reduce?: BinReducer; } +/** + * Draws two-dimensional lines by connecting control points. + * + * The following channels are required: + * + * - **x** - the horizontal position of control points; bound to the *x* scale + * - **y** - the vertical position of control points; bound to the *y* scale + * + * Separate lines are drawn for each series. The optional **z** channel + * specifies a categorical value to group data into series; if not specified, it + * defaults to **stroke** if a channel, or **fill** if a channel. + * + * The **fill** defaults to none. The **stroke** defaults to currentColor if the + * fill is none, and to none otherwise. If the stroke is defined as a channel, + * the line will be broken into contiguous overlapping segments when the stroke + * color changes; the stroke color will apply to the interval spanning the + * current data point and the following data point. This behavior also applies + * to the **fill**, **fillOpacity**, **strokeOpacity**, **strokeWidth**, + * **opacity**, **href**, **title**, and **ariaLabel** channels. When any of + * these channels are used, setting an explicit **z** channel (possibly to null) + * is strongly recommended. The **strokeWidth** defaults to 1.5, the + * **strokeLinecap** and **strokeLinejoin** default to *round*, and the + * **strokeMiterlimit** defaults to 1. + * + * Points along the line are connected in input order. Likewise, if there are + * multiple series via the *z*, *fill*, or *stroke* channel, the series are + * drawn in input order such that the last series is drawn on top. Typically, + * the data is already in sorted order, such as chronological for time series; + * if sorting is needed, consider a **sort** transform. + * + * The line mark supports **curve** options to control interpolation between + * points, and **marker** options to add a marker (such as a dot or an + * arrowhead) on each of the control points. The default curve is *auto*, which + * is equivalent to *linear* if there is no projection, and otherwise uses the + * associated projection. If any of the *x* or *y* values are invalid + * (undefined, null, or NaN), the line will be interrupted, resulting in a break + * that divides the line shape into multiple segments. If a line segment + * consists of only a single point, it may appear invisible unless rendered with + * rounded or square line caps. In addition, some curves such as *cardinal-open* + * only render a visible segment if it contains multiple points. + * + * If neither the **x** nor **y** options are specified, *data* is assumed to be + * an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that + * **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …]. + */ export function line(data?: Data, options?: LineOptions): Line; +/** + * Similar to **line** except that if the **x** option is not specified, it + * defaults to the identity function and assumes that *data* = [*x₀*, *x₁*, + * *x₂*, …]. If the **y** option is not specified, it defaults to [0, 1, 2, …]. + * For example, the following draws a vertical line chart of a temperature + * series: + * + * ```js + * Plot.lineX(observations.map(d => d.temperature)) + * ``` + * + * If the **interval** option is specified, the **binY** transform is implicitly + * applied to the specified *options*. The reducer of the output *x* channel may + * be specified via the **reduce** option, which defaults to *first*. To default + * to zero instead of showing gaps in data, as when the observed value + * represents a quantity, use the *sum* reducer. + * + * The **interval** option is recommended to “regularize” sampled data; for + * example, if your data represents timestamped temperature measurements and you + * expect one sample per day, use "day" as the interval: + * + * ```js + * Plot.lineX(observations, {y: "date", x: "temperature", interval: "day"}) + * ``` + */ export function lineX(data?: Data, options?: LineXOptions): Line; +/** + * Similar to **line** except that if the **y** option is not specified, it + * defaults to the identity function and assumes that *data* = [*y₀*, *y₁*, + * *y₂*, …]. If the **x** option is not specified, it defaults to [0, 1, 2, …]. + * For example, the following draws a horizontal line chart of a temperature + * series: + * + * ```js + * Plot.lineY(observations.map(d => d.temperature)) + * ``` + * + * If the **interval** option is specified, the **binX** transform is implicitly + * applied to the specified *options*. The reducer of the output *y* channel may + * be specified via the **reduce** option, which defaults to *first*. To default + * to zero instead of showing gaps in data, as when the observed value + * represents a quantity, use the *sum* reducer. + * + * The **interval** option is recommended to “regularize” sampled data; for + * example, if your data represents timestamped temperature measurements and you + * expect one sample per day, use "day" as the interval: + * + * ```js + * Plot.lineY(observations, {x: "date", y: "temperature", interval: "day"}) + * ``` + */ export function lineY(data?: Data, options?: LineYOptions): Line; +/** The line mark. */ export class Line extends RenderableMark {} From 466fad61e1bdaa085a70f302a9021aef24dcc583 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Tue, 28 Mar 2023 15:21:58 +0200 Subject: [PATCH 2/3] z --- src/marks/line.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/marks/line.d.ts b/src/marks/line.d.ts index 553d3b6af1..b40347ef97 100644 --- a/src/marks/line.d.ts +++ b/src/marks/line.d.ts @@ -17,7 +17,7 @@ export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOption y?: ChannelValueSpec; /** - * If specified, the **z** channel defines series + * If specified, the **z** channel defines series, creating separate lines. */ z?: ChannelValue; } From ac7f744e9e7bd423277888082b99910ec619f3ed Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Wed, 29 Mar 2023 21:05:20 -0700 Subject: [PATCH 3/3] edits --- src/marks/area.d.ts | 18 +++-- src/marks/line.d.ts | 160 ++++++++++++++++++++------------------------ 2 files changed, 85 insertions(+), 93 deletions(-) diff --git a/src/marks/area.d.ts b/src/marks/area.d.ts index 24082291ca..2840209084 100644 --- a/src/marks/area.d.ts +++ b/src/marks/area.d.ts @@ -38,8 +38,8 @@ export interface AreaOptions extends MarkOptions, StackOptions, CurveOptions { /** * The optional ordinal **z** channel, for grouping data into (possibly - * stacked) series to be drawn as separate areas. If not specified, it - * defaults to **fill** if a channel, or **stroke** if a channel. + * stacked) series to be drawn as separate areas; defaults to **fill** if a + * channel, or **stroke** if a channel. */ z?: ChannelValue; } @@ -59,9 +59,9 @@ export interface AreaXOptions extends Omit, BinOptions /** * The vertical position channel, typically bound to the *y* scale; defaults - * to the zero-based index of the data. + * to the zero-based index of the data [0, 1, 2, …]. * - * If an **interval** is specified, **x** values are binned accordingly, + * If an **interval** is specified, **y** values are binned accordingly, * allowing zeroes for empty bins instead of interpolating across gaps. This * is recommended to “regularize” sampled data; for example, if your data * represents timestamped observations and you expect one observation per day, @@ -77,6 +77,9 @@ export interface AreaXOptions extends Omit, BinOptions * ```js * Plot.areaX(data, {y: "value", interval: 0.5, reduce: "count"}) * ``` + * + * To default to zero instead of showing gaps in data, as when the observed + * value represents a quantity, use the *sum* reducer. */ reduce?: BinReducer; } @@ -85,7 +88,7 @@ export interface AreaXOptions extends Omit, BinOptions export interface AreaYOptions extends Omit, BinOptions { /** * The horizontal position channel, typically bound to the *x* scale; defaults - * to the zero-based index of the data. + * to the zero-based index of the data [0, 1, 2, …]. * * If an **interval** is specified, **x** values are binned accordingly, * allowing zeroes for empty bins instead of interpolating across gaps. This @@ -114,6 +117,9 @@ export interface AreaYOptions extends Omit, BinOptions * ```js * Plot.areaY(records, {x: "Date", interval: "month", reduce: "count"}) * ``` + * + * To default to zero instead of showing gaps in data, as when the observed + * value represents a quantity, use the *sum* reducer. */ reduce?: BinReducer; } @@ -148,7 +154,7 @@ export function area(data?: Data, options?: AreaOptions): Area; export function areaX(data?: Data, options?: AreaXOptions): Area; /** - * Returns a new horizontall-oriented area for the given *data* and *options*, + * Returns a new horizontally-oriented area for the given *data* and *options*, * where the baseline and topline share **x** values, as in a time-series area * chart where time goes right→. * diff --git a/src/marks/line.d.ts b/src/marks/line.d.ts index b40347ef97..c05235418f 100644 --- a/src/marks/line.d.ts +++ b/src/marks/line.d.ts @@ -7,17 +7,19 @@ import type {BinOptions, BinReducer} from "../transforms/bin.js"; /** Options for the line mark. */ export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOptions { /** - * The horizontal position channel, typically bound to the *x* scale. + * The required horizontal position channel, typically bound to the *x* scale. */ x?: ChannelValueSpec; /** - * The vertical position channel, typically bound to the *y* scale. + * The required vertical position channel, typically bound to the *y* scale. */ y?: ChannelValueSpec; /** - * If specified, the **z** channel defines series, creating separate lines. + * The optional ordinal **z** channel, for grouping data into (possibly + * stacked) series to be drawn as separate lines. If not specified, it + * defaults to **fill** if a channel, or **stroke** if a channel. */ z?: ChannelValue; } @@ -25,21 +27,28 @@ export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOption /** Options for the lineX mark. */ export interface LineXOptions extends LineOptions, BinOptions { /** - * The vertical position channel, typically bound to the *y* scale. If an - * interval is specified, the *data* is binned according to the interval, - * allowing to show zeroes for empty slots, instead of interpolating between - * defined control points. + * The vertical position channel, typically bound to the *y* scale; defaults + * to the zero-based index of the data [0, 1, 2, …]. + * + * If an **interval** is specified, **y** values are binned accordingly, + * allowing zeroes for empty bins instead of interpolating across gaps. This + * is recommended to “regularize” sampled data; for example, if your data + * represents timestamped observations and you expect one observation per day, + * use *day* as the **interval**. */ y?: ChannelValueDenseBinSpec; /** - * Reducer for when the **y** channel is binned with an **interval**. For - * example, to create a vertical density plot (count of *y* values binned - * every 0.5): + * How to reduce **x** values when the **y** channel is binned with an + * **interval**; defaults to *first*. For example, to create a vertical + * density plot (count of *y* values binned every 0.5): * * ```js - * Plot.lineX(data, { y: "value", interval: 0.5, reduce: "count" }) + * Plot.lineX(data, {y: "value", interval: 0.5, reduce: "count"}) * ``` + * + * To default to zero instead of showing gaps in data, as when the observed + * value represents a quantity, use the *sum* reducer. */ reduce?: BinReducer; } @@ -47,92 +56,75 @@ export interface LineXOptions extends LineOptions, BinOptions { /** Options for the lineY mark. */ export interface LineYOptions extends LineOptions, BinOptions { /** - * The horizontal position channel, typically bound to the *x* scale. If an - * interval is specified, the *data* is binned according to the interval, - * allowing to show zeroes for empty slots, instead of interpolating between - * defined control points. + * The horizontal position channel, typically bound to the *x* scale; defaults + * to the zero-based index of the data [0, 1, 2, …]. + * + * If an **interval** is specified, **x** values are binned accordingly, + * allowing zeroes for empty bins instead of interpolating across gaps. This + * is recommended to “regularize” sampled data; for example, if your data + * represents timestamped observations and you expect one observation per day, + * use *day* as the **interval**. */ x?: ChannelValueDenseBinSpec; /** - * Reducer for when the **x** channel is binned with an **interval**. For - * example, to create a line chart of the count of records by - * month—showing zeros for empty months: + * How to reduce **y** values when the **x** channel is binned with an + * **interval**; defaults to *first*. For example, for a line chart of the + * count of records by month: * * ```js * Plot.lineY(records, {x: "Date", interval: "month", reduce: "count"}) * ``` + * + * To default to zero instead of showing gaps in data, as when the observed + * value represents a quantity, use the *sum* reducer. */ reduce?: BinReducer; } /** - * Draws two-dimensional lines by connecting control points. - * - * The following channels are required: - * - * - **x** - the horizontal position of control points; bound to the *x* scale - * - **y** - the vertical position of control points; bound to the *y* scale + * Returns a new line for the given *data* and *options* by connecting control + * points. If neither the **x** nor **y** options are specified, *data* is + * assumed to be an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] + * such that **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …]. * - * Separate lines are drawn for each series. The optional **z** channel - * specifies a categorical value to group data into series; if not specified, it - * defaults to **stroke** if a channel, or **fill** if a channel. + * Points along the line are connected in input order. If there are multiple + * series via the **z**, **fill**, or **stroke** channel, series are drawn in + * input order such that the last series is drawn on top. Typically *data* is + * already in sorted order, such as chronological for time series; if needed, + * consider a **sort** transform. * - * The **fill** defaults to none. The **stroke** defaults to currentColor if the - * fill is none, and to none otherwise. If the stroke is defined as a channel, - * the line will be broken into contiguous overlapping segments when the stroke - * color changes; the stroke color will apply to the interval spanning the - * current data point and the following data point. This behavior also applies - * to the **fill**, **fillOpacity**, **strokeOpacity**, **strokeWidth**, - * **opacity**, **href**, **title**, and **ariaLabel** channels. When any of - * these channels are used, setting an explicit **z** channel (possibly to null) - * is strongly recommended. The **strokeWidth** defaults to 1.5, the - * **strokeLinecap** and **strokeLinejoin** default to *round*, and the - * **strokeMiterlimit** defaults to 1. + * If any **x** or **y** values are invalid (undefined, null, or NaN), the line + * will be interrupted, resulting in a break that divides the line shape into + * multiple segments. If a line segment consists of only a single point, it may + * appear invisible unless rendered with rounded or square line caps. In + * addition, some curves such as *cardinal-open* only render a visible segment + * if it contains multiple points. * - * Points along the line are connected in input order. Likewise, if there are - * multiple series via the *z*, *fill*, or *stroke* channel, the series are - * drawn in input order such that the last series is drawn on top. Typically, - * the data is already in sorted order, such as chronological for time series; - * if sorting is needed, consider a **sort** transform. - * - * The line mark supports **curve** options to control interpolation between - * points, and **marker** options to add a marker (such as a dot or an - * arrowhead) on each of the control points. The default curve is *auto*, which - * is equivalent to *linear* if there is no projection, and otherwise uses the - * associated projection. If any of the *x* or *y* values are invalid - * (undefined, null, or NaN), the line will be interrupted, resulting in a break - * that divides the line shape into multiple segments. If a line segment - * consists of only a single point, it may appear invisible unless rendered with - * rounded or square line caps. In addition, some curves such as *cardinal-open* - * only render a visible segment if it contains multiple points. - * - * If neither the **x** nor **y** options are specified, *data* is assumed to be - * an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that - * **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …]. + * Variable aesthetic channels are supported: if the **stroke** is defined as a + * channel, the line will be broken into contiguous overlapping segments when + * the stroke color changes; the stroke color will apply to the interval + * spanning the current data point and the following data point. This behavior + * also applies to the **fill**, **fillOpacity**, **strokeOpacity**, + * **strokeWidth**, **opacity**, **href**, **title**, and **ariaLabel** + * channels. When any of these channels are used, setting an explicit **z** + * channel (possibly to null) is strongly recommended. */ export function line(data?: Data, options?: LineOptions): Line; /** - * Similar to **line** except that if the **x** option is not specified, it - * defaults to the identity function and assumes that *data* = [*x₀*, *x₁*, - * *x₂*, …]. If the **y** option is not specified, it defaults to [0, 1, 2, …]. - * For example, the following draws a vertical line chart of a temperature - * series: + * Like line, except that **x** defaults to the identity function assuming that + * *data* = [*x₀*, *x₁*, *x₂*, …] and **y** defaults to the zero-based index [0, + * 1, 2, …]. For example, to draw a vertical line chart of a temperature series: * * ```js - * Plot.lineX(observations.map(d => d.temperature)) + * Plot.lineX(observations, {x: "temperature"}) * ``` * - * If the **interval** option is specified, the **binY** transform is implicitly - * applied to the specified *options*. The reducer of the output *x* channel may - * be specified via the **reduce** option, which defaults to *first*. To default - * to zero instead of showing gaps in data, as when the observed value - * represents a quantity, use the *sum* reducer. - * - * The **interval** option is recommended to “regularize” sampled data; for - * example, if your data represents timestamped temperature measurements and you - * expect one sample per day, use "day" as the interval: + * The **interval** option is recommended to “regularize” sampled data via an + * implicit binY transform. For example, if your data represents timestamped + * temperature measurements and you expect one sample per day, use *day* as the + * interval: * * ```js * Plot.lineX(observations, {y: "date", x: "temperature", interval: "day"}) @@ -141,25 +133,19 @@ export function line(data?: Data, options?: LineOptions): Line; export function lineX(data?: Data, options?: LineXOptions): Line; /** - * Similar to **line** except that if the **y** option is not specified, it - * defaults to the identity function and assumes that *data* = [*y₀*, *y₁*, - * *y₂*, …]. If the **x** option is not specified, it defaults to [0, 1, 2, …]. - * For example, the following draws a horizontal line chart of a temperature + * Like line, except **y** defaults to the identity function and assumes that + * *data* = [*y₀*, *y₁*, *y₂*, …] and **x** defaults to the zero-based index [0, + * 1, 2, …]. For example, to draw a horizontal line chart of a temperature * series: * * ```js - * Plot.lineY(observations.map(d => d.temperature)) + * Plot.lineY(observations, {y: "temperature"}) * ``` * - * If the **interval** option is specified, the **binX** transform is implicitly - * applied to the specified *options*. The reducer of the output *y* channel may - * be specified via the **reduce** option, which defaults to *first*. To default - * to zero instead of showing gaps in data, as when the observed value - * represents a quantity, use the *sum* reducer. - * - * The **interval** option is recommended to “regularize” sampled data; for - * example, if your data represents timestamped temperature measurements and you - * expect one sample per day, use "day" as the interval: + * The **interval** option is recommended to “regularize” sampled data via an + * implicit binX transform. For example, if your data represents timestamped + * temperature measurements and you expect one sample per day, use *day* as the + * interval: * * ```js * Plot.lineY(observations, {x: "date", y: "temperature", interval: "day"})