From 9f8a1ba18fe1a17510bd8700b3f342e005ba8c79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Fri, 17 Mar 2023 19:08:52 +0100 Subject: [PATCH 1/3] document normalize --- src/transforms/normalize.d.ts | 105 ++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/src/transforms/normalize.d.ts b/src/transforms/normalize.d.ts index 316f2240cd..c0ea6d398f 100644 --- a/src/transforms/normalize.d.ts +++ b/src/transforms/normalize.d.ts @@ -22,12 +22,117 @@ export interface NormalizeOptions { basis?: NormalizeBasis; } +/** + * Normalize series values relative to the given basis. For example, if the + * series values are [*x₀*, *x₁*, *x₂*, …] and the *first* basis is used, the + * mapped series values would be [*x₀* / *x₀*, *x₁* / *x₀*, *x₂* / *x₀*, …] as + * in an index chart. The **basis** option specifies how to normalize the series + * values. + * + * The following basis methods are supported: + * + * * *first* - the first value, as in an index chart; the default + * * *last* - the last value + * * *min* - the minimum value + * * *max* - the maximum value + * * *mean* - the mean value (average) + * * *median* - the median value + * * *pXX* - the percentile value, where XX is a number in [00,99] + * * *sum* - the sum of values + * * *extent* - the minimum is mapped to zero, and the maximum to one + * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation + * * a function to be passed an array of values, returning the desired basis + */ export function normalizeX(options?: T & NormalizeOptions): Transformed; +/** + * Normalize series values relative to the given basis. For example, if the + * series values are [*x₀*, *x₁*, *x₂*, …] and the *first* basis is used, the + * mapped series values would be [*x₀* / *x₀*, *x₁* / *x₀*, *x₂* / *x₀*, …] as + * in an index chart. The **basis** option specifies how to normalize the series + * values. + * + * The following basis methods are supported: + * + * * *first* - the first value, as in an index chart; the default + * * *last* - the last value + * * *min* - the minimum value + * * *max* - the maximum value + * * *mean* - the mean value (average) + * * *median* - the median value + * * *pXX* - the percentile value, where XX is a number in [00,99] + * * *sum* - the sum of values + * * *extent* - the minimum is mapped to zero, and the maximum to one + * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation + * * a function to be passed an array of values, returning the desired basis + */ export function normalizeX(basis?: NormalizeBasis, options?: T): Transformed; +/** + * Normalize series values relative to the given basis. For example, if the + * series values are [*y₀*, *y₁*, *y₂*, …] and the *first* basis is used, the + * mapped series values would be [*y₀* / *y₀*, *y₁* / *y₀*, *y₂* / *y₀*, …] as + * in an index chart. The **basis** option specifies how to normalize the series + * values. + * + * The following basis methods are supported: + * + * * *first* - the first value, as in an index chart; the default + * * *last* - the last value + * * *min* - the minimum value + * * *max* - the maximum value + * * *mean* - the mean value (average) + * * *median* - the median value + * * *pXX* - the percentile value, where XX is a number in [00,99] + * * *sum* - the sum of values + * * *extent* - the minimum is mapped to zero, and the maximum to one + * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation + * * a function to be passed an array of values, returning the desired basis + */ export function normalizeY(options?: T & NormalizeOptions): Transformed; +/** + * Normalize series values relative to the given basis. For example, if the + * series values are [*y₀*, *y₁*, *y₂*, …] and the *first* basis is used, the + * mapped series values would be [*y₀* / *y₀*, *y₁* / *y₀*, *y₂* / *y₀*, …] as + * in an index chart. The **basis** option specifies how to normalize the series + * values. + * + * The following basis methods are supported: + * + * * *first* - the first value, as in an index chart; the default + * * *last* - the last value + * * *min* - the minimum value + * * *max* - the maximum value + * * *mean* - the mean value (average) + * * *median* - the median value + * * *pXX* - the percentile value, where XX is a number in [00,99] + * * *sum* - the sum of values + * * *extent* - the minimum is mapped to zero, and the maximum to one + * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation + * * a function to be passed an array of values, returning the desired basis + */ export function normalizeY(basis?: NormalizeBasis, options?: T): Transformed; +/** + * Returns a normalize map method for the given *basis*, suitable for use with Plot.map. + * + * The following basis methods are supported: + * + * * *first* - the first value, as in an index chart; the default + * * *last* - the last value + * * *min* - the minimum value + * * *max* - the maximum value + * * *mean* - the mean value (average) + * * *median* - the median value + * * *pXX* - the percentile value, where XX is a number in [00,99] + * * *sum* - the sum of values + * * *extent* - the minimum is mapped to zero, and the maximum to one + * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation + * * a function to be passed an array of values, returning the desired basis + * + * ```js + * Plot.map({y: Plot.normalize("first")}, {x: "Date", y: "Close", stroke: "Symbol"}) + * ``` + */ export function normalize(basis: NormalizeBasis): Map; From a22ea1b25e8f3ef1adc74e509dc1ab43b4e0114d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Mon, 20 Mar 2023 09:40:09 +0100 Subject: [PATCH 2/3] avoid duplication --- src/transforms/normalize.d.ts | 44 ----------------------------------- 1 file changed, 44 deletions(-) diff --git a/src/transforms/normalize.d.ts b/src/transforms/normalize.d.ts index c0ea6d398f..11f80eb9b4 100644 --- a/src/transforms/normalize.d.ts +++ b/src/transforms/normalize.d.ts @@ -44,28 +44,6 @@ export interface NormalizeOptions { * * a function to be passed an array of values, returning the desired basis */ export function normalizeX(options?: T & NormalizeOptions): Transformed; - -/** - * Normalize series values relative to the given basis. For example, if the - * series values are [*x₀*, *x₁*, *x₂*, …] and the *first* basis is used, the - * mapped series values would be [*x₀* / *x₀*, *x₁* / *x₀*, *x₂* / *x₀*, …] as - * in an index chart. The **basis** option specifies how to normalize the series - * values. - * - * The following basis methods are supported: - * - * * *first* - the first value, as in an index chart; the default - * * *last* - the last value - * * *min* - the minimum value - * * *max* - the maximum value - * * *mean* - the mean value (average) - * * *median* - the median value - * * *pXX* - the percentile value, where XX is a number in [00,99] - * * *sum* - the sum of values - * * *extent* - the minimum is mapped to zero, and the maximum to one - * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation - * * a function to be passed an array of values, returning the desired basis - */ export function normalizeX(basis?: NormalizeBasis, options?: T): Transformed; /** @@ -90,28 +68,6 @@ export function normalizeX(basis?: NormalizeBasis, options?: T): Transformed< * * a function to be passed an array of values, returning the desired basis */ export function normalizeY(options?: T & NormalizeOptions): Transformed; - -/** - * Normalize series values relative to the given basis. For example, if the - * series values are [*y₀*, *y₁*, *y₂*, …] and the *first* basis is used, the - * mapped series values would be [*y₀* / *y₀*, *y₁* / *y₀*, *y₂* / *y₀*, …] as - * in an index chart. The **basis** option specifies how to normalize the series - * values. - * - * The following basis methods are supported: - * - * * *first* - the first value, as in an index chart; the default - * * *last* - the last value - * * *min* - the minimum value - * * *max* - the maximum value - * * *mean* - the mean value (average) - * * *median* - the median value - * * *pXX* - the percentile value, where XX is a number in [00,99] - * * *sum* - the sum of values - * * *extent* - the minimum is mapped to zero, and the maximum to one - * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation - * * a function to be passed an array of values, returning the desired basis - */ export function normalizeY(basis?: NormalizeBasis, options?: T): Transformed; /** From 579f9ae717de817889734877ae984733c2403fd0 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 23 Mar 2023 09:53:37 -0700 Subject: [PATCH 3/3] edits --- src/transforms/normalize.d.ts | 62 +++++++++++++++++++---------------- 1 file changed, 34 insertions(+), 28 deletions(-) diff --git a/src/transforms/normalize.d.ts b/src/transforms/normalize.d.ts index 11f80eb9b4..a5219e22f5 100644 --- a/src/transforms/normalize.d.ts +++ b/src/transforms/normalize.d.ts @@ -14,24 +14,27 @@ export type NormalizeBasisName = | "extent" | ReducerPercentile; -export type NormalizeBasisFunction = (index: number[], values: any[]) => any; +export type NormalizeBasisFunction = (index: number[], values: any[]) => number; +/** How to normalize series values. */ export type NormalizeBasis = NormalizeBasisName | NormalizeBasisFunction; +/** Options for the normalize transform. */ export interface NormalizeOptions { basis?: NormalizeBasis; } /** - * Normalize series values relative to the given basis. For example, if the - * series values are [*x₀*, *x₁*, *x₂*, …] and the *first* basis is used, the - * mapped series values would be [*x₀* / *x₀*, *x₁* / *x₀*, *x₂* / *x₀*, …] as - * in an index chart. The **basis** option specifies how to normalize the series - * values. + * Groups data into series using the first channel of *z*, *fill*, or *stroke* + * (if any), then derives new *x*, *x1*, and *x2* channels for each + * corresponding input channel by normalizing to the given *basis*. For example, + * if the series values are [*x₀*, *x₁*, *x₂*, …] and the *first* basis is used, + * the derived series values would be [*x₀* / *x₀*, *x₁* / *x₀*, *x₂* / *x₀*, …] + * as in an index chart. * - * The following basis methods are supported: + * The **basis** option specifies how to normalize series values. It can be: * - * * *first* - the first value, as in an index chart; the default + * * *first* (default) - the first value, as in an index chart * * *last* - the last value * * *min* - the minimum value * * *max* - the maximum value @@ -40,22 +43,23 @@ export interface NormalizeOptions { * * *pXX* - the percentile value, where XX is a number in [00,99] * * *sum* - the sum of values * * *extent* - the minimum is mapped to zero, and the maximum to one - * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation - * * a function to be passed an array of values, returning the desired basis + * * *deviation* - subtract the mean, then divide by the standard deviation + * * a function to be passed an array of series values, returning a number */ export function normalizeX(options?: T & NormalizeOptions): Transformed; export function normalizeX(basis?: NormalizeBasis, options?: T): Transformed; /** - * Normalize series values relative to the given basis. For example, if the - * series values are [*y₀*, *y₁*, *y₂*, …] and the *first* basis is used, the - * mapped series values would be [*y₀* / *y₀*, *y₁* / *y₀*, *y₂* / *y₀*, …] as - * in an index chart. The **basis** option specifies how to normalize the series - * values. + * Groups data into series using the first channel of *z*, *fill*, or *stroke* + * (if any), then derives new *y*, *y1*, and *y2* channels for each + * corresponding input channel by normalizing to the given *basis*. For example, + * if the series values are [*y₀*, *y₁*, *y₂*, …] and the *first* basis is used, + * the derived series values would be [*y₀* / *y₀*, *y₁* / *y₀*, *y₂* / *y₀*, …] + * as in an index chart. * - * The following basis methods are supported: + * The **basis** option specifies how to normalize series values. It can be: * - * * *first* - the first value, as in an index chart; the default + * * *first* (default) - the first value, as in an index chart * * *last* - the last value * * *min* - the minimum value * * *max* - the maximum value @@ -64,18 +68,24 @@ export function normalizeX(basis?: NormalizeBasis, options?: T): Transformed< * * *pXX* - the percentile value, where XX is a number in [00,99] * * *sum* - the sum of values * * *extent* - the minimum is mapped to zero, and the maximum to one - * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation - * * a function to be passed an array of values, returning the desired basis + * * *deviation* - subtract the mean, then divide by the standard deviation + * * a function to be passed an array of series values, returning a number */ export function normalizeY(options?: T & NormalizeOptions): Transformed; export function normalizeY(basis?: NormalizeBasis, options?: T): Transformed; /** - * Returns a normalize map method for the given *basis*, suitable for use with Plot.map. + * Given a normalize *basis*, returns a corresponding map implementation for use + * with the map transform, allowing the normalization of arbitrary channels + * instead of only *x* and *y*. For example, to normalize the *title* channel: * - * The following basis methods are supported: + * ```js + * Plot.map({title: Plot.normalize("first")}, {x: "Date", title: "Close", stroke: "Symbol"}) + * ``` + * + * The **basis** option specifies how to normalize series values. It can be: * - * * *first* - the first value, as in an index chart; the default + * * *first* (default) - the first value, as in an index chart * * *last* - the last value * * *min* - the minimum value * * *max* - the maximum value @@ -84,11 +94,7 @@ export function normalizeY(basis?: NormalizeBasis, options?: T): Transformed< * * *pXX* - the percentile value, where XX is a number in [00,99] * * *sum* - the sum of values * * *extent* - the minimum is mapped to zero, and the maximum to one - * * *deviation* - each value is transformed by subtracting the mean and then dividing by the standard deviation - * * a function to be passed an array of values, returning the desired basis - * - * ```js - * Plot.map({y: Plot.normalize("first")}, {x: "Date", y: "Close", stroke: "Symbol"}) - * ``` + * * *deviation* - subtract the mean, then divide by the standard deviation + * * a function to be passed an array of series values, returning a number */ export function normalize(basis: NormalizeBasis): Map;