Skip to content

Add dtype keyword argument to sum and prod #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Sep 17, 2021
34 changes: 30 additions & 4 deletions spec/API_specification/statistical_functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Calculates the minimum value of the input array `x`.
- if the minimum value was computed over the entire array, a zero-dimensional array containing the minimum value; otherwise, a non-zero-dimensional array containing the minimum values. The returned array must have the same data type as `x`.

(function-prod)=
### prod(x, /, *, axis=None, keepdims=False)
### prod(x, /, *, axis=None, dtype=None, keepdims=False)

Calculates the product of input array `x` elements.

Expand All @@ -105,6 +105,19 @@ Calculates the product of input array `x` elements.

- axis or axes along which products must be computed. By default, the product must be computed over the entire array. If a tuple of integers, products must be computed over multiple axes. Default: `None`.

- **dtype**: _Optional\[ <dtype> ]_

- data type of the returned array. If `None`,

- if the default data type corresponding to the data type "kind" (integer or floating-point) of `x` has a smaller range of values than the data type of `x` (e.g., `x` has data type `int64` and the default data type is `int32`, or `x` has data type `uint64` and the default data type is `int64`), the returned array must have the same data type as `x`.
- otherwise, the returned array must have the default data type corresponding to the data type "kind" (integer or floating-point) of `x`.

If the data type (either specified or resolved) differs from the data type of `x`, the input array should be cast to the specified data type before computing the product. Default: `None`.

```{note}
This keyword argument is intended to help prevent data type overflows.
```

- **keepdims**: _bool_

- If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`.
Expand All @@ -113,7 +126,7 @@ Calculates the product of input array `x` elements.

- **out**: _<array>_

- if the product was computed over the entire array, a zero-dimensional array containing the product; otherwise, a non-zero-dimensional array containing the products. The returned array must have the same data type as `x`.
- if the product was computed over the entire array, a zero-dimensional array containing the product; otherwise, a non-zero-dimensional array containing the products. The returned array must have a data type as described by the `dtype` parameter above.

(function-std)=
### std(x, /, *, axis=None, correction=0.0, keepdims=False)
Expand Down Expand Up @@ -145,7 +158,7 @@ Calculates the standard deviation of the input array `x`.
- if the standard deviation was computed over the entire array, a zero-dimensional array containing the standard deviation; otherwise, a non-zero-dimensional array containing the standard deviations. The returned array must have the default floating-point data type.

(function-sum)=
### sum(x, /, *, axis=None, keepdims=False)
### sum(x, /, *, axis=None, dtype=None, keepdims=False)

Calculates the sum of the input array `x`.

Expand All @@ -159,6 +172,19 @@ Calculates the sum of the input array `x`.

- axis or axes along which sums must be computed. By default, the sum must be computed over the entire array. If a tuple of integers, sums must be computed over multiple axes. Default: `None`.

- **dtype**: _Optional\[ <dtype> ]_

- data type of the returned array. If `None`,

- if the default data type corresponding to the data type "kind" (integer or floating-point) of `x` has a smaller range of values than the data type of `x` (e.g., `x` has data type `int64` and the default data type is `int32`, or `x` has data type `uint64` and the default data type is `int64`), the returned array must have the same data type as `x`.
- otherwise, the returned array must have the default data type corresponding to the data type "kind" (integer or floating-point) of `x`.

If the data type (either specified or resolved) differs from the data type of `x`, the input array should be cast to the specified data type before computing the sum. Default: `None`.

```{note}
This keyword argument is intended to help prevent data type overflows.
```

- **keepdims**: _bool_

- If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`.
Expand All @@ -167,7 +193,7 @@ Calculates the sum of the input array `x`.

- **out**: _<array>_

- if the sum was computed over the entire array, a zero-dimensional array containing the sum; otherwise, an array containing the sums. The returned array must have the same data type as `x`.
- if the sum was computed over the entire array, a zero-dimensional array containing the sum; otherwise, an array containing the sums. The returned array must have a data type as described by the `dtype` parameter above.

(function-var)=
### var(x, /, *, axis=None, correction=0.0, keepdims=False)
Expand Down