From cf2880682aa912e134eaaa0dbb2b5f542621c0e5 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 13 Sep 2021 10:08:06 -0700 Subject: [PATCH 1/5] Specify `mean` behavior when provided a 0D array --- spec/API_specification/statistical_functions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/spec/API_specification/statistical_functions.md b/spec/API_specification/statistical_functions.md index 39ea18280..a5b966c62 100644 --- a/spec/API_specification/statistical_functions.md +++ b/spec/API_specification/statistical_functions.md @@ -45,6 +45,12 @@ Calculates the maximum value of the input array `x`. Calculates the arithmetic mean of the input array `x`. +#### Special Cases + +For an input array `x`, + +- if axis (or axes) along which arithmetic means is zero-dimensional, the computed mean is `NaN`. + #### Parameters - **x**: _<array>_ From 0168a1f7e259a57bf7fa19680d9e0dec65c4fb89 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 13 Sep 2021 10:11:14 -0700 Subject: [PATCH 2/5] Specify `prod` behavior when provided a 0D array --- spec/API_specification/statistical_functions.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/statistical_functions.md b/spec/API_specification/statistical_functions.md index a5b966c62..a21eb87f2 100644 --- a/spec/API_specification/statistical_functions.md +++ b/spec/API_specification/statistical_functions.md @@ -47,9 +47,9 @@ Calculates the arithmetic mean of the input array `x`. #### Special Cases -For an input array `x`, +For a floating-point input array `x`, -- if axis (or axes) along which arithmetic means is zero-dimensional, the computed mean is `NaN`. +- if axis (or axes) along which arithmetic means is zero-dimensional, the arithmetic mean is `NaN`. #### Parameters @@ -101,6 +101,12 @@ Calculates the minimum value of the input array `x`. Calculates the product of input array `x` elements. +#### Special Cases + +For an input array `x`, + +- if an axis (or axes) along which to compute products is zero-dimensional, the product is `1`. + #### Parameters - **x**: _<array>_ From 8e7a73c148e2a4e162f8a3b586c47952825111c0 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 13 Sep 2021 10:12:03 -0700 Subject: [PATCH 3/5] Specify `sum` behavior when provided a 0D array --- spec/API_specification/statistical_functions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/spec/API_specification/statistical_functions.md b/spec/API_specification/statistical_functions.md index a21eb87f2..24fa205c7 100644 --- a/spec/API_specification/statistical_functions.md +++ b/spec/API_specification/statistical_functions.md @@ -161,6 +161,12 @@ Calculates the standard deviation of the input array `x`. Calculates the sum of the input array `x`. +#### Special Cases + +For an input array `x`, + +- if an axis (or axes) along which to compute products is zero-dimensional, the sum is `0`. + #### Parameters - **x**: _<array>_ From 9229e978165b066234d3bbe98cd6dca8aaa9b400 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 13 Sep 2021 10:24:28 -0700 Subject: [PATCH 4/5] Rephrase special cases and add special cases for other stats reductions --- .../statistical_functions.md | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/statistical_functions.md b/spec/API_specification/statistical_functions.md index 24fa205c7..5c1cadd34 100644 --- a/spec/API_specification/statistical_functions.md +++ b/spec/API_specification/statistical_functions.md @@ -47,9 +47,9 @@ Calculates the arithmetic mean of the input array `x`. #### Special Cases -For a floating-point input array `x`, +For a floating-point input array `x`, let `N` equal the number of elements over which to compute the arithmetic mean and -- if axis (or axes) along which arithmetic means is zero-dimensional, the arithmetic mean is `NaN`. +- if `N` is `0`, the arithmetic mean is `NaN`. #### Parameters @@ -103,9 +103,9 @@ Calculates the product of input array `x` elements. #### Special Cases -For an input array `x`, +For an input array `x`, let `N` equal the number of elements over which to compute the product and -- if an axis (or axes) along which to compute products is zero-dimensional, the product is `1`. +- if `N` is `0`, the product is `1` (i.e., the empty product). #### Parameters @@ -132,6 +132,12 @@ For an input array `x`, Calculates the standard deviation of the input array `x`. +#### Special Cases + +For a floating-point input array `x`, let `N` equal the number of elements over which to compute the standard deviation and + +- if `N - correction` is less than or equal to `0`, the standard deviation is `NaN`. + #### Parameters - **x**: _<array>_ @@ -163,9 +169,9 @@ Calculates the sum of the input array `x`. #### Special Cases -For an input array `x`, +For an input array `x`, let `N` equal the number of elements over which to compute the sum and -- if an axis (or axes) along which to compute products is zero-dimensional, the sum is `0`. +- if `N` is `0`, the sum is `0` (i.e., the empty sum). #### Parameters @@ -192,6 +198,12 @@ For an input array `x`, Calculates the variance of the input array `x`. +#### Special Cases + +For a floating-point input array `x`, let `N` equal the number of elements over which to compute the variance and + +- if `N - correction` is less than or equal to `0`, the variance is `NaN`. + #### Parameters - **x**: _<array>_ From 12415cbdcb224a67e3eb52911c34d3da5d88adbd Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 13 Sep 2021 10:42:14 -0700 Subject: [PATCH 5/5] Add guidance for min and max when `x` is 0D --- spec/API_specification/statistical_functions.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/spec/API_specification/statistical_functions.md b/spec/API_specification/statistical_functions.md index 5c1cadd34..51f46f399 100644 --- a/spec/API_specification/statistical_functions.md +++ b/spec/API_specification/statistical_functions.md @@ -20,6 +20,10 @@ A conforming implementation of the array API standard must provide and support t Calculates the maximum value of the input array `x`. +```{note} +When the number of elements over which to compute the maximum value is zero, the maximum value is implementation-defined. Specification-compliant libraries may choose to error, return a sentinel value (e.g., if `x` is a floating-point input array, return `NaN`), or return the minimum possible value for the input array `x` data type (e.g., if `x` is a floating-point array, return `-infinity`). +``` + #### Parameters - **x**: _<array>_ @@ -76,6 +80,10 @@ For a floating-point input array `x`, let `N` equal the number of elements over Calculates the minimum value of the input array `x`. +```{note} +When the number of elements over which to compute the minimum value is zero, the minimum value is implementation-defined. Specification-compliant libraries may choose to error, return a sentinel value (e.g., if `x` is a floating-point input array, return `NaN`), or return the maximum possible value for the input array `x` data type (e.g., if `x` is a floating-point array, return `+infinity`). +``` + #### Parameters - **x**: _<array>_