From dcd6c00b96a84ec851a7d042caf7d39c75cd59e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 17 Mar 2023 11:01:02 +0100 Subject: [PATCH 1/7] document Plot.window remarks: * *k* is not optional * *shift* is deprecated * added the *strict* option to README --- README.md | 2 +- src/transforms/window.d.ts | 120 ++++++++++++++++++++++++++++++++++++- 2 files changed, 119 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ada8ff287f..4172a9fb91 100644 --- a/README.md +++ b/README.md @@ -2457,7 +2457,7 @@ Like [Plot.mapY](#plotmapymap-options), but applies the normalize map method wit Plot.map({y: Plot.window(24)}, {x: "Date", y: "Close", stroke: "Symbol"}) ``` -Returns a window map method for the given window size *k*, suitable for use with Plot.map. For additional options to the window transform, replace the number *k* with an object with properties *k*, *anchor*, or *reduce*. +Returns a window map method for the given window size *k*, suitable for use with Plot.map. For additional options to the window transform, replace the number *k* with an object with properties *k*, *anchor*, *reduce*, or *strict*. #### Plot.windowX(*k*, *options*) diff --git a/src/transforms/window.d.ts b/src/transforms/window.d.ts index de9e028f4a..0aa378151f 100644 --- a/src/transforms/window.d.ts +++ b/src/transforms/window.d.ts @@ -22,19 +22,135 @@ export type WindowReducerFunction = (values: any[]) => any; export type WindowReducer = WindowReducerName | WindowReducerFunction; export interface WindowOptions { - k?: number; + /** + * The size —number of consecutive values— in the window; includes the current + * value. + */ + k: number; + + /** + * The reducer returns a summary statistic from the **k** values in the + * current window, say to compute rolling averages, rolling minimums, or + * rolling maximums. The following window reducers are supported: + * + * * *min* - the minimum + * * *max* - the maximum + * * *mean* - the mean (average) + * * *median* - the median + * * *mode* - the mode (most common occurrence) + * * *pXX* - the percentile value, where XX is a number in [00,99] + * * *sum* - the sum of values + * * *deviation* - the standard deviation + * * *variance* - the variance per [Welford’s + * algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm) + * * *difference* - the difference between the last and first window value + * * *ratio* - the ratio of the last and first window value + * * *first* - the first value + * * *last* - the last value + * * a function to be passed an array of *k* values + * + * Defaults to mean. + */ reduce?: WindowReducer; + + /** + * How to align the window: + * + * * *start* - the current value is the first element in the window + * * *middle* - the current value is in the middle of the window (rounded to + * the left if the size **k** is even) + * * *end* - the current value is the last element in the window. + * + * Defaults to middle. + */ anchor?: "start" | "middle" | "end"; - shift?: "leading" | "centered" | "trailing"; // deprecated! + + /** The shift option is deprecated. See **anchor**. */ + shift?: never; // was "leading" | "centered" | "trailing"; + + /** If the **strict** option is true, the output start values or end values or + * both (depending on the **anchor**) of each series may be undefined since + * there are not enough elements to create a window of size **k**; output + * values may also be undefined if some of the input values in the + * corresponding window are undefined. If the **strict** option is false (the + * default), the window will be automatically truncated as needed, and + * undefined input values are ignored. For example, if **k** is 24 and + * **anchor** is *middle*, then the initial 11 values have effective window + * sizes of 13, 14, 15, … 23, and likewise the last 12 values have effective + * window sizes of 23, 22, 21, … 12. Values computed with a truncated window + * may be noisy; if you would prefer to not show this data, set the **strict** + * option to true. + */ strict?: boolean; } +/** + * Computes a moving window of the *x* channel around each data point and then + * derives a summary statistic from values in the current window, say to compute + * rolling averages, rolling minimums, or rolling maximums. The window options + * can be specified as the first argument, or grouped with the *options*. For + * example, the following are equivalent: + * + * ```js + * Plot.windowX(24, {x: "Anomaly", y: "Date"}); + * Plot.windowX({k: 24, reduce: "mean", x: "Anomaly", y: "Date"}); + * Plot.windowX({k: 24, reduce: "mean"}, {x: "Anomaly", y: "Date"}); + * ``` + */ export function windowX(options?: T & WindowOptions): Transformed; +/** + * Computes a moving window of the *x* channel around each data point and then + * derives a summary statistic from values in the current window, say to compute + * rolling averages, rolling minimums, or rolling maximums. The window options + * can be specified as the first argument, or grouped with the *options*. For + * example, the following are equivalent: + * + * ```js + * Plot.windowX(24, {x: "Anomaly", y: "Date"}); + * Plot.windowX({k: 24, reduce: "mean", x: "Anomaly", y: "Date"}); + * Plot.windowX({k: 24, reduce: "mean"}, {x: "Anomaly", y: "Date"}); + * ``` + */ export function windowX(windowOptions?: WindowOptions | number, options?: T): Transformed; +/** + * Computes a moving window of the *y* channel around each data point and then + * derives a summary statistic from values in the current window, say to compute + * rolling averages, rolling minimums, or rolling maximums. The window options + * can be specified as the first argument, or grouped with the *options*. For + * example, the following are equivalent: + * + * ```js + * Plot.windowY(24, {x: "Date", y: "Anomaly"}); + * Plot.windowY({k: 24, reduce: "mean", x: "Date", y: "Anomaly"}); + * Plot.windowY({k: 24, reduce: "mean"}, {x: "Date", y: "Anomaly"}); + * ``` + */ export function windowY(options?: T & WindowOptions): Transformed; +/** + * Computes a moving window of the *y* channel around each data point and then + * derives a summary statistic from values in the current window, say to compute + * rolling averages, rolling minimums, or rolling maximums. The window options + * can be specified as the first argument, or grouped with the *options*. For + * example, the following are equivalent: + * + * ```js + * Plot.windowY(24, {x: "Date", y: "Anomaly"}); + * Plot.windowY({k: 24, reduce: "mean", x: "Date", y: "Anomaly"}); + * Plot.windowY({k: 24, reduce: "mean"}, {x: "Date", y: "Anomaly"}); + * ``` + */ export function windowY(windowOptions?: WindowOptions | number, options?: T): Transformed; +/** + * Returns a window map method suitable for use with Plot.map. The options are + * the window size *k*, or an object with properties *k*, *anchor*, *reduce*, or + * *strict*. + * + * ```js + * Plot.map({y: Plot.window(24)}, {x: "Date", y: "Close", stroke: "Symbol"}) + * ``` + */ export function window(options?: WindowOptions | number): Map; From ccb8e3041872f7161e05b1f4fda00844ba052e26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 17 Mar 2023 15:00:15 +0100 Subject: [PATCH 2/7] adopt @deprecated --- src/transforms/window.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/transforms/window.d.ts b/src/transforms/window.d.ts index 0aa378151f..93ab62490c 100644 --- a/src/transforms/window.d.ts +++ b/src/transforms/window.d.ts @@ -65,8 +65,8 @@ export interface WindowOptions { */ anchor?: "start" | "middle" | "end"; - /** The shift option is deprecated. See **anchor**. */ - shift?: never; // was "leading" | "centered" | "trailing"; + /** @deprecated See **anchor**. */ + shift?: "leading" | "centered" | "trailing"; /** If the **strict** option is true, the output start values or end values or * both (depending on the **anchor**) of each series may be undefined since From cf4efeea5a829186a46289a3ed64afe4420cd832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Mon, 20 Mar 2023 09:27:59 +0100 Subject: [PATCH 3/7] Update src/transforms/window.d.ts Co-authored-by: Mike Bostock --- src/transforms/window.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/transforms/window.d.ts b/src/transforms/window.d.ts index 93ab62490c..25bf6b46f6 100644 --- a/src/transforms/window.d.ts +++ b/src/transforms/window.d.ts @@ -23,7 +23,7 @@ export type WindowReducer = WindowReducerName | WindowReducerFunction; export interface WindowOptions { /** - * The size —number of consecutive values— in the window; includes the current + * The size (number of consecutive values) in the window; includes the current * value. */ k: number; From a0c368767365be04a5059b48c71510c74cd107c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Mon, 20 Mar 2023 09:28:06 +0100 Subject: [PATCH 4/7] Update src/transforms/window.d.ts Co-authored-by: Mike Bostock --- src/transforms/window.d.ts | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/src/transforms/window.d.ts b/src/transforms/window.d.ts index 25bf6b46f6..14b1518bb3 100644 --- a/src/transforms/window.d.ts +++ b/src/transforms/window.d.ts @@ -98,20 +98,6 @@ export interface WindowOptions { * ``` */ export function windowX(options?: T & WindowOptions): Transformed; - -/** - * Computes a moving window of the *x* channel around each data point and then - * derives a summary statistic from values in the current window, say to compute - * rolling averages, rolling minimums, or rolling maximums. The window options - * can be specified as the first argument, or grouped with the *options*. For - * example, the following are equivalent: - * - * ```js - * Plot.windowX(24, {x: "Anomaly", y: "Date"}); - * Plot.windowX({k: 24, reduce: "mean", x: "Anomaly", y: "Date"}); - * Plot.windowX({k: 24, reduce: "mean"}, {x: "Anomaly", y: "Date"}); - * ``` - */ export function windowX(windowOptions?: WindowOptions | number, options?: T): Transformed; /** From 317a6d4a88c47194eeb9766050550b7accaf72f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Mon, 20 Mar 2023 09:28:14 +0100 Subject: [PATCH 5/7] Update src/transforms/window.d.ts Co-authored-by: Mike Bostock --- src/transforms/window.d.ts | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/src/transforms/window.d.ts b/src/transforms/window.d.ts index 14b1518bb3..728c4e23d8 100644 --- a/src/transforms/window.d.ts +++ b/src/transforms/window.d.ts @@ -114,20 +114,6 @@ export function windowX(windowOptions?: WindowOptions | number, options?: T): * ``` */ export function windowY(options?: T & WindowOptions): Transformed; - -/** - * Computes a moving window of the *y* channel around each data point and then - * derives a summary statistic from values in the current window, say to compute - * rolling averages, rolling minimums, or rolling maximums. The window options - * can be specified as the first argument, or grouped with the *options*. For - * example, the following are equivalent: - * - * ```js - * Plot.windowY(24, {x: "Date", y: "Anomaly"}); - * Plot.windowY({k: 24, reduce: "mean", x: "Date", y: "Anomaly"}); - * Plot.windowY({k: 24, reduce: "mean"}, {x: "Date", y: "Anomaly"}); - * ``` - */ export function windowY(windowOptions?: WindowOptions | number, options?: T): Transformed; /** From 4e50c81014518b98e1a30feccb7123148430c128 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Mon, 20 Mar 2023 09:28:20 +0100 Subject: [PATCH 6/7] Update src/transforms/window.d.ts Co-authored-by: Mike Bostock --- src/transforms/window.d.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/transforms/window.d.ts b/src/transforms/window.d.ts index 728c4e23d8..8699064253 100644 --- a/src/transforms/window.d.ts +++ b/src/transforms/window.d.ts @@ -68,7 +68,8 @@ export interface WindowOptions { /** @deprecated See **anchor**. */ shift?: "leading" | "centered" | "trailing"; - /** If the **strict** option is true, the output start values or end values or + /** + * If the **strict** option is true, the output start values or end values or * both (depending on the **anchor**) of each series may be undefined since * there are not enough elements to create a window of size **k**; output * values may also be undefined if some of the input values in the From 053049fc4a0bde678121457a0cdfb3097fb106fb Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Mon, 20 Mar 2023 09:45:13 -0700 Subject: [PATCH 7/7] tweaks --- src/transforms/window.d.ts | 67 +++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 37 deletions(-) diff --git a/src/transforms/window.d.ts b/src/transforms/window.d.ts index 8699064253..4cf18610d0 100644 --- a/src/transforms/window.d.ts +++ b/src/transforms/window.d.ts @@ -29,39 +29,32 @@ export interface WindowOptions { k: number; /** - * The reducer returns a summary statistic from the **k** values in the - * current window, say to compute rolling averages, rolling minimums, or - * rolling maximums. The following window reducers are supported: + * How to produce a summary statistic from the **k** values in the current + * window. The reducer may be specified as: * * * *min* - the minimum * * *max* - the maximum - * * *mean* - the mean (average) + * * *mean* (default) - the mean (average) * * *median* - the median * * *mode* - the mode (most common occurrence) * * *pXX* - the percentile value, where XX is a number in [00,99] * * *sum* - the sum of values * * *deviation* - the standard deviation - * * *variance* - the variance per [Welford’s - * algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm) + * * *variance* - the variance per [Welford’s algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm) * * *difference* - the difference between the last and first window value * * *ratio* - the ratio of the last and first window value * * *first* - the first value * * *last* - the last value - * * a function to be passed an array of *k* values - * - * Defaults to mean. + * * a function to be passed an array of **k** values */ reduce?: WindowReducer; /** - * How to align the window: - * - * * *start* - the current value is the first element in the window - * * *middle* - the current value is in the middle of the window (rounded to - * the left if the size **k** is even) - * * *end* - the current value is the last element in the window. + * How to align the rolling window, placing the current value: * - * Defaults to middle. + * * *start* - as the first element in the window + * * *middle* (default) - in the middle of the window, rounding down if **k** is even + * * *end* - as the last element in the window */ anchor?: "start" | "middle" | "end"; @@ -69,28 +62,28 @@ export interface WindowOptions { shift?: "leading" | "centered" | "trailing"; /** - * If the **strict** option is true, the output start values or end values or - * both (depending on the **anchor**) of each series may be undefined since - * there are not enough elements to create a window of size **k**; output - * values may also be undefined if some of the input values in the - * corresponding window are undefined. If the **strict** option is false (the - * default), the window will be automatically truncated as needed, and - * undefined input values are ignored. For example, if **k** is 24 and - * **anchor** is *middle*, then the initial 11 values have effective window - * sizes of 13, 14, 15, … 23, and likewise the last 12 values have effective - * window sizes of 23, 22, 21, … 12. Values computed with a truncated window - * may be noisy; if you would prefer to not show this data, set the **strict** - * option to true. + * If true, the output start values or end values or both (depending on the + * **anchor**) of each series may be undefined since there are not enough + * elements to create a window of size **k**; output values may also be + * undefined if some of the input values in the corresponding window are + * undefined. + * + * If false (the default), the window will be automatically truncated as + * needed, and undefined input values are ignored. For example, if **k** is 24 + * and **anchor** is *middle*, then the initial 11 values have effective + * window sizes of 13, 14, 15, … 23, and likewise the last 12 values have + * effective window sizes of 23, 22, 21, … 12. Values computed with a + * truncated window may be noisy; if you would prefer to not show this data, + * set the **strict** option to true. */ strict?: boolean; } /** - * Computes a moving window of the *x* channel around each data point and then + * Computes a moving window of *x*, *x1*, and *x2* channel values and then * derives a summary statistic from values in the current window, say to compute - * rolling averages, rolling minimums, or rolling maximums. The window options - * can be specified as the first argument, or grouped with the *options*. For - * example, the following are equivalent: + * a rolling average. The window options can be specified as the first argument, + * or grouped with the *options*. For example, the following are equivalent: * * ```js * Plot.windowX(24, {x: "Anomaly", y: "Date"}); @@ -102,11 +95,11 @@ export function windowX(options?: T & WindowOptions): Transformed; export function windowX(windowOptions?: WindowOptions | number, options?: T): Transformed; /** - * Computes a moving window of the *y* channel around each data point and then - * derives a summary statistic from values in the current window, say to compute - * rolling averages, rolling minimums, or rolling maximums. The window options - * can be specified as the first argument, or grouped with the *options*. For - * example, the following are equivalent: + * Computes a moving window of *y*, *y1*, and *y2* channel values around and + * then derives a summary statistic from values in the current window, say to + * compute a rolling average. The window options can be specified as the first + * argument, or grouped with the *options*. For example, the following are + * equivalent: * * ```js * Plot.windowY(24, {x: "Date", y: "Anomaly"});