From 67aed1719dc20d893c3f6676f97f56581fbb9c15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 24 Mar 2023 11:45:24 +0100 Subject: [PATCH 1/4] document tickX/tickY --- src/marks/tick.d.ts | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/marks/tick.d.ts b/src/marks/tick.d.ts index cf04debaf9..80a523683b 100644 --- a/src/marks/tick.d.ts +++ b/src/marks/tick.d.ts @@ -2,20 +2,60 @@ import type {ChannelValueSpec} from "../channel.js"; import type {InsetOptions} from "../inset.js"; import type {Data, MarkOptions, RenderableMark} from "../mark.js"; +/** Options for the tickX mark. */ export interface TickXOptions extends MarkOptions, Omit { + /** The horizontal position of the tick; a channel bound to the *x* scale. */ x?: ChannelValueSpec; + /** + * The vertical position of the tick; an optional categorical channel bound to + * the *y* scale. + */ y?: ChannelValueSpec; } +/** Options for the tickY mark. */ export interface TickYOptions extends MarkOptions, Omit { + /** The vertical position of the tick; a channel bound to the *y* scale. */ y?: ChannelValueSpec; + /** + * The horizontal position of the tick; an optional categorical channel bound + * to the *x* scale. + */ x?: ChannelValueSpec; } +/** + * Returns a new tickX mark for the given *data* and *options*. The **x** + * channel indicates the vertical position of the tick, and the optional **y** + * channel defines a band scale, for categorical ticks. For example, to create a + * barcode plot of penguins’ weights: + * + * ```js + * Plot.tickY(penguins, { y: "body_mass_g", x: "sex", stroke: "species" }) + * ``` + * + * **x** defaults to identity, assuming that *data* contains numbers. If the + * secondary dimension **y** is quantitative instead of ordinal, use **ruleX**. + */ export function tickX(data?: Data, options?: TickXOptions): TickX; +/** + * Returns a new tickY mark for the given *data* and *options*. The **y** + * channel indicates the vertical position of the tick, and the optional **x** + * channel defines a band scale, for categorical ticks. For example, to create a + * barcode plot of penguins’ weights: + * + * ```js + * Plot.tickY(penguins, { y: "body_mass_g", x: "sex", stroke: "species" }) + * ``` + * + * **y** defaults to identity, assuming that *data* contains numbers. If the + * secondary dimension **x** is quantitative instead of ordinal, use **ruleY**. + */ export function tickY(data?: Data, options?: TickYOptions): TickY; +/** The tickX mark. */ export class TickX extends RenderableMark {} +/** The tickY mark. */ export class TickY extends RenderableMark {} From f04080c9b6e1e6331c743efef7b51b10a995cb09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 24 Mar 2023 12:29:34 +0100 Subject: [PATCH 2/4] fixes --- src/marks/tick.d.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/marks/tick.d.ts b/src/marks/tick.d.ts index 80a523683b..b99ce17b84 100644 --- a/src/marks/tick.d.ts +++ b/src/marks/tick.d.ts @@ -26,12 +26,12 @@ export interface TickYOptions extends MarkOptions, Omit Date: Thu, 30 Mar 2023 16:38:41 +0200 Subject: [PATCH 3/4] typically bound to the scale --- src/marks/tick.d.ts | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/src/marks/tick.d.ts b/src/marks/tick.d.ts index b99ce17b84..79a4884b35 100644 --- a/src/marks/tick.d.ts +++ b/src/marks/tick.d.ts @@ -4,22 +4,30 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js"; /** Options for the tickX mark. */ export interface TickXOptions extends MarkOptions, Omit { - /** The horizontal position of the tick; a channel bound to the *x* scale. */ + /** + * The horizontal position of the tick; a channel typically bound to the *x* + * scale. + */ x?: ChannelValueSpec; + /** - * The vertical position of the tick; an optional categorical channel bound to - * the *y* scale. + * The vertical position of the tick; an optional categorical channel + * typically bound to the *y* scale. */ y?: ChannelValueSpec; } /** Options for the tickY mark. */ export interface TickYOptions extends MarkOptions, Omit { - /** The vertical position of the tick; a channel bound to the *y* scale. */ + /** + * The vertical position of the tick; a channel typically bound to the *y* + * scale. + */ y?: ChannelValueSpec; + /** - * The horizontal position of the tick; an optional categorical channel bound - * to the *x* scale. + * The horizontal position of the tick; an optional categorical channel + * typically bound to the *x* scale. */ x?: ChannelValueSpec; } From e51af860509fd91cf9456cefa4d7ee218bcf417b Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 30 Mar 2023 09:02:59 -0700 Subject: [PATCH 4/4] edits --- src/marks/tick.d.ts | 55 +++++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/src/marks/tick.d.ts b/src/marks/tick.d.ts index 79a4884b35..2be9af42e8 100644 --- a/src/marks/tick.d.ts +++ b/src/marks/tick.d.ts @@ -5,14 +5,18 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js"; /** Options for the tickX mark. */ export interface TickXOptions extends MarkOptions, Omit { /** - * The horizontal position of the tick; a channel typically bound to the *x* - * scale. + * The required horizontal position of the tick; a channel typically bound to + * the *x* scale. */ x?: ChannelValueSpec; /** - * The vertical position of the tick; an optional categorical channel - * typically bound to the *y* scale. + * The optional vertical position of the tick; a categorical channel typically + * bound to the *y* scale. If not specified, the tick spans the vertical + * extent of the frame; otherwise the *y* scale must be a *band* scale. + * + * If **y** represents quantitative or temporal values, use a ruleX mark + * instead. */ y?: ChannelValueSpec; } @@ -20,45 +24,52 @@ export interface TickXOptions extends MarkOptions, Omit { /** - * The vertical position of the tick; a channel typically bound to the *y* - * scale. + * The required vertical position of the tick; a channel typically bound to + * the *y* scale. */ y?: ChannelValueSpec; /** - * The horizontal position of the tick; an optional categorical channel - * typically bound to the *x* scale. + * The optional horizontal position of the tick; a categorical channel + * typically bound to the *x* scale. If not specified, the tick spans the + * horizontal extent of the frame; otherwise the *x* scale must be a *band* + * scale. + * + * If **x** represents quantitative or temporal values, use a ruleY mark + * instead. */ x?: ChannelValueSpec; } /** - * Returns a new tickX mark for the given *data* and *options*. The **x** - * channel specifies the horizontal position of the tick, and the optional **y** - * categorical channel specifies its vertical position. For example, to create - * a horizontal barcode plot of penguins’ weights: + * Returns a new horizontally-positioned tickX mark (a vertical line, |) for the + * given *data* and *options*. The **x** channel specifies the tick’s horizontal + * position and defaults to identity, assuming that *data* = [*x₀*, *x₁*, *x₂*, + * …]; the optional **y** categorical channel specifies its vertical position. + * For example, for a horizontal barcode plot of penguins’ weights: * * ```js - * Plot.tickX(penguins, { x: "body_mass_g", y: "sex", stroke: "species" }) + * Plot.tickX(penguins, {x: "body_mass_g", y: "sex", stroke: "species"}) * ``` * - * **x** defaults to identity, assuming that *data* contains numbers. If the - * secondary dimension **y** is quantitative instead of ordinal, use **ruleX**. + * If **y** represents quantitative or temporal values, use a ruleX mark + * instead. */ export function tickX(data?: Data, options?: TickXOptions): TickX; /** - * Returns a new tickY mark for the given *data* and *options*. The **y** - * channel specifies the vertical position of the tick, and the optional **x** - * categorical channel specifies its horizontal position. For example, to create - * a vertical barcode plot of penguins’ weights: + * Returns a new vertically-positioned tickY mark (a horizontal line, —) for the + * given *data* and *options*. The **y** channel specifies the vertical position + * of the tick and defaults to identity, assuming that *data* = [*y₀*, *y₁*, + * *y₂*, …]; the optional **x** categorical channel specifies its horizontal + * position. For example, fpr a vertical barcode plot of penguins’ weights: * * ```js - * Plot.tickY(penguins, { y: "body_mass_g", x: "sex", stroke: "species" }) + * Plot.tickY(penguins, {y: "body_mass_g", x: "sex", stroke: "species"}) * ``` * - * **y** defaults to identity, assuming that *data* contains numbers. If the - * secondary dimension **x** is quantitative instead of ordinal, use **ruleY**. + * If **x** represents quantitative or temporal values, use a ruleY mark + * instead. */ export function tickY(data?: Data, options?: TickYOptions): TickY;