From 705b1f575b684fdb95a0e749434978a767b9bb89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 17 Mar 2023 18:30:41 +0100 Subject: [PATCH 1/2] document select --- src/transforms/select.d.ts | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/transforms/select.d.ts b/src/transforms/select.d.ts index 74fe57a4fa..334e248b25 100644 --- a/src/transforms/select.d.ts +++ b/src/transforms/select.d.ts @@ -13,16 +13,50 @@ export interface SelectOptions { z?: ChannelValue; } +/** + * Selects points from each series (usually defined by *stroke*, *fill* or *z*) + * based on a selector. The selector can be specified either as a function which + * receives as input the index of the series, the shorthand “first” or “last”, + * or as a {*key*: *value*} object with exactly one *key* being the name of a + * channel and the *value* being a function which receives as input the index of + * the series and the channel values. The *value* may alternatively be specified + * as the shorthand “min” and “max” which respectively select the minimum and + * maximum points for the specified channel. + */ export function select(selector: Selector, options?: T & SelectOptions): Transformed; +/** + * Selects the first point of each series (usually defined by *stroke*, *fill* + * or *z*) in input order. + */ export function selectFirst(options?: T & SelectOptions): Transformed; +/** + * Selects the last point of each series (usually defined by *stroke*, *fill* + * or *z*) in input order. + */ export function selectLast(options?: T & SelectOptions): Transformed; +/** + * Selects the first point of each series (usually defined by *stroke*, *fill* + * or *z*) in ascending *x* order. + */ export function selectMinX(options?: T & SelectOptions): Transformed; +/** + * Selects the first point of each series (usually defined by *stroke*, *fill* + * or *z*) in ascending *y* order. + */ export function selectMinY(options?: T & SelectOptions): Transformed; +/** + * Selects the first point of each series (usually defined by *stroke*, *fill* + * or *z*) in descending *x* order. + */ export function selectMaxX(options?: T & SelectOptions): Transformed; +/** + * Selects the first point of each series (usually defined by *stroke*, *fill* + * or *z*) in descending *y* order. + */ export function selectMaxY(options?: T & SelectOptions): Transformed; From 6221663270789d9348a5cf9879837f7804ae6da5 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Wed, 22 Mar 2023 18:22:28 -0700 Subject: [PATCH 2/2] edits --- src/transforms/select.d.ts | 61 +++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 20 deletions(-) diff --git a/src/transforms/select.d.ts b/src/transforms/select.d.ts index 334e248b25..642921431f 100644 --- a/src/transforms/select.d.ts +++ b/src/transforms/select.d.ts @@ -7,56 +7,77 @@ export type SelectorFunction = (index: number[], values: any[] | null) => number export type SelectorChannel = {[key in keyof T]?: SelectorName | SelectorFunction}; +/** How to select points within each series. */ export type Selector = SelectorName | SelectorFunction | SelectorChannel; +/** Options for the select transform. */ export interface SelectOptions { z?: ChannelValue; } /** - * Selects points from each series (usually defined by *stroke*, *fill* or *z*) - * based on a selector. The selector can be specified either as a function which - * receives as input the index of the series, the shorthand “first” or “last”, - * or as a {*key*: *value*} object with exactly one *key* being the name of a - * channel and the *value* being a function which receives as input the index of - * the series and the channel values. The *value* may alternatively be specified - * as the shorthand “min” and “max” which respectively select the minimum and - * maximum points for the specified channel. + * Groups points into series according to the *z* channel, or the *fill* or + * *stroke* channel if no *z* channel is provided, then selects points from each + * series based on the given selector. The selector can be specified as: + * + * - *first* - the first point by input order + * - *last* - the last point by input order + * - a {*channel*: *min*} object - the minimum point by the given *channel*’s value + * - a {*channel*: *max*} object - the maximum point by the given *channel*’s value + * - a {*channel*: function} object to filter based on series index and channel values + * - a function to filter based on series index + * + * For example to select the maximum point of the *y* channel, like selectMaxY: + * + * ```js + * Plot.text(data, Plot.select({y: "max"}, options)) + * ``` + * + * When the selector is specified as a function, it is passed the index of each + * series as input, along with channel values if a *channel* name was given; it + * must return the corresponding index of selected points (a subset of the + * passed-in index). */ export function select(selector: Selector, options?: T & SelectOptions): Transformed; /** - * Selects the first point of each series (usually defined by *stroke*, *fill* - * or *z*) in input order. + * Groups points into series according to the *z* channel, or the *fill* or + * *stroke* channel if no *z* channel is provided, and then selects the first + * point from each series in input order. */ export function selectFirst(options?: T & SelectOptions): Transformed; /** - * Selects the last point of each series (usually defined by *stroke*, *fill* - * or *z*) in input order. + * Groups points into series according to the *z* channel, or the *fill* or + * *stroke* channel if no *z* channel is provided, and then selects the last + * point from each series in input order. */ export function selectLast(options?: T & SelectOptions): Transformed; /** - * Selects the first point of each series (usually defined by *stroke*, *fill* - * or *z*) in ascending *x* order. + * Groups points into series according to the *z* channel, or the *fill* or + * *stroke* channel if no *z* channel is provided, and then selects the minimum + * point from each series based on *x* channel value. */ export function selectMinX(options?: T & SelectOptions): Transformed; /** - * Selects the first point of each series (usually defined by *stroke*, *fill* - * or *z*) in ascending *y* order. + * Groups points into series according to the *z* channel, or the *fill* or + * *stroke* channel if no *z* channel is provided, and then selects the minimum + * point from each series based on *y* channel value. */ export function selectMinY(options?: T & SelectOptions): Transformed; /** - * Selects the first point of each series (usually defined by *stroke*, *fill* - * or *z*) in descending *x* order. + * Groups points into series according to the *z* channel, or the *fill* or + * *stroke* channel if no *z* channel is provided, and then selects the maximum + * point from each series based on *x* channel value. */ export function selectMaxX(options?: T & SelectOptions): Transformed; /** - * Selects the first point of each series (usually defined by *stroke*, *fill* - * or *z*) in descending *y* order. + * Groups points into series according to the *z* channel, or the *fill* or + * *stroke* channel if no *z* channel is provided, and then selects the maximum + * point from each series based on *y* channel value. */ export function selectMaxY(options?: T & SelectOptions): Transformed;