Skip to content

Commit 85d6b31

Browse files
authored
Specify behavior of statistical reductions over the empty set (#262)
* Specify `mean` behavior when provided a 0D array * Specify `prod` behavior when provided a 0D array * Specify `sum` behavior when provided a 0D array * Rephrase special cases and add special cases for other stats reductions * Add guidance for min and max when `x` is 0D
1 parent 7499649 commit 85d6b31

File tree

1 file changed

+38
-0
lines changed

1 file changed

+38
-0
lines changed

spec/API_specification/statistical_functions.md

+38
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ A conforming implementation of the array API standard must provide and support t
2020

2121
Calculates the maximum value of the input array `x`.
2222

23+
```{note}
24+
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`).
25+
```
26+
2327
#### Parameters
2428

2529
- **x**: _<array>_
@@ -45,6 +49,12 @@ Calculates the maximum value of the input array `x`.
4549

4650
Calculates the arithmetic mean of the input array `x`.
4751

52+
#### Special Cases
53+
54+
For a floating-point input array `x`, let `N` equal the number of elements over which to compute the arithmetic mean and
55+
56+
- if `N` is `0`, the arithmetic mean is `NaN`.
57+
4858
#### Parameters
4959

5060
- **x**: _<array>_
@@ -74,6 +84,10 @@ Calculates the arithmetic mean of the input array `x`.
7484
7585
Calculates the minimum value of the input array `x`.
7686
87+
```{note}
88+
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`).
89+
```
90+
7791
#### Parameters
7892

7993
- **x**: _<array>_
@@ -99,6 +113,12 @@ Calculates the minimum value of the input array `x`.
99113

100114
Calculates the product of input array `x` elements.
101115

116+
#### Special Cases
117+
118+
For an input array `x`, let `N` equal the number of elements over which to compute the product and
119+
120+
- if `N` is `0`, the product is `1` (i.e., the empty product).
121+
102122
#### Parameters
103123

104124
- **x**: _<array>_
@@ -124,6 +144,12 @@ Calculates the product of input array `x` elements.
124144

125145
Calculates the standard deviation of the input array `x`.
126146

147+
#### Special Cases
148+
149+
For a floating-point input array `x`, let `N` equal the number of elements over which to compute the standard deviation and
150+
151+
- if `N - correction` is less than or equal to `0`, the standard deviation is `NaN`.
152+
127153
#### Parameters
128154

129155
- **x**: _<array>_
@@ -157,6 +183,12 @@ Calculates the standard deviation of the input array `x`.
157183
158184
Calculates the sum of the input array `x`.
159185
186+
#### Special Cases
187+
188+
For an input array `x`, let `N` equal the number of elements over which to compute the sum and
189+
190+
- if `N` is `0`, the sum is `0` (i.e., the empty sum).
191+
160192
#### Parameters
161193
162194
- **x**: _<array>_
@@ -182,6 +214,12 @@ Calculates the sum of the input array `x`.
182214
183215
Calculates the variance of the input array `x`.
184216
217+
#### Special Cases
218+
219+
For a floating-point input array `x`, let `N` equal the number of elements over which to compute the variance and
220+
221+
- if `N - correction` is less than or equal to `0`, the variance is `NaN`.
222+
185223
#### Parameters
186224
187225
- **x**: _<array>_

0 commit comments

Comments
 (0)