From ae4bc1cafc0c3b044306324a3d6b938006abac46 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 12 Jul 2023 23:27:13 -0700 Subject: [PATCH 1/5] Add specification for computing the cumulative sum --- .../statistical_functions.rst | 1 + .../_draft/statistical_functions.py | 62 ++++++++++++++++++- 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/spec/draft/API_specification/statistical_functions.rst b/spec/draft/API_specification/statistical_functions.rst index 23cd2cb1d..20e02b3f9 100644 --- a/spec/draft/API_specification/statistical_functions.rst +++ b/spec/draft/API_specification/statistical_functions.rst @@ -18,6 +18,7 @@ Objects in API :toctree: generated :template: method.rst + cumulative_sum max mean min diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 93faaf31e..5a8e1aea3 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -1,6 +1,66 @@ from ._types import Optional, Tuple, Union, array, dtype +def cumulative_sum( + x: array, + /, + *, + axis: Optional[int] = None, + dtype: Optional[dtype] = None, + startpoint: bool = False, + endpoint: bool = True, +) -> array: + """ + Calculates the cumulative sum of elements in the input array ``x``. + + Parameters + ---------- + x: array + input array. Should have a numeric data type. + axis: Optional[int] + axis along which a cumulative sum must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative sum by counting from the last dimension. + + If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required. + dtype: Optional[dtype] + data type of the returned array. If ``None``, + + - if the default data type corresponding to the data type "kind" (integer, real-valued floating-point, or complex 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``. + - if the default data type corresponding to the data type "kind" of ``x`` has the same or a larger range of values than the data type of ``x``, + - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. + - if ``x`` has a complex floating-point data type, the returned array must have the default complex floating-point data type. + - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. + - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). + + 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:: + keyword argument is intended to help prevent data type overflows. + + startpoint: bool + boolean indicating whether to include the initial value as the first value in the output. Default: ``False``. + endpoint: bool + boolean indicating whether to include the total sum as the last value in the output. Default: ``True``. + + Returns + ------- + out: array + an array containing the cumulative sums. The returned array must have a data type as described by the ``dtype`` parameter above. + + Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: + + - if ``startpoint`` and ``endpoint`` are ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if only one of ``startpoint`` and ``endpoint`` is ``True``, the returned array must have the same shape as ``x``. + - if ``startpoint`` and ``endpoint`` are ``False``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N-1``. + + Notes + ----- + + **Special Cases** + + For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`. + """ + + def max( x: array, /, @@ -317,4 +377,4 @@ def var( """ -__all__ = ["max", "mean", "min", "prod", "std", "sum", "var"] +__all__ = ["cumulative_sum", "max", "mean", "min", "prod", "std", "sum", "var"] From 2e0b224466ed68ae0cbbac64dcd6ef179b4b9f58 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 27 Jul 2023 01:28:08 -0700 Subject: [PATCH 2/5] Rename kwargs and remove `endpoint` --- .../_draft/statistical_functions.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 5a8e1aea3..ac339f37b 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -7,8 +7,7 @@ def cumulative_sum( *, axis: Optional[int] = None, dtype: Optional[dtype] = None, - startpoint: bool = False, - endpoint: bool = True, + include_initial: bool = False, ) -> array: """ Calculates the cumulative sum of elements in the input array ``x``. @@ -36,10 +35,8 @@ def cumulative_sum( .. note:: keyword argument is intended to help prevent data type overflows. - startpoint: bool - boolean indicating whether to include the initial value as the first value in the output. Default: ``False``. - endpoint: bool - boolean indicating whether to include the total sum as the last value in the output. Default: ``True``. + include_initial: bool + boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the additive identity (i.e., zero). Default: ``False``. Returns ------- @@ -48,9 +45,8 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - - if ``startpoint`` and ``endpoint`` are ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - - if only one of ``startpoint`` and ``endpoint`` is ``True``, the returned array must have the same shape as ``x``. - - if ``startpoint`` and ``endpoint`` are ``False``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N-1``. + - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes ----- From 8083e5beeeb2ad39a57b52911608d9493092d15e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Tue, 19 Sep 2023 14:16:56 -0700 Subject: [PATCH 3/5] Add guidance for empty arrays --- src/array_api_stubs/_draft/statistical_functions.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index ffb5c8514..102d5b93e 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -48,7 +48,9 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if ``include_initial`` is ``True``, + - if ``N`` is greater than zero, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if ``N`` is zero (i.e., ``x`` is an empty array), the returned array must have the same shape as ``x``. - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes From 3228d4c70f0890d067df9d59446642392fc90df7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 21 Sep 2023 01:40:57 -0700 Subject: [PATCH 4/5] Fix formatting --- src/array_api_stubs/_draft/statistical_functions.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 102d5b93e..81a124b0d 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -27,7 +27,9 @@ def cumulative_sum( data type of the returned array. If ``None``, - if the default data type corresponding to the data type "kind" (integer, real-valued floating-point, or complex 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``. + - if the default data type corresponding to the data type "kind" of ``x`` has the same or a larger range of values than the data type of ``x``, + - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. - if ``x`` has a complex floating-point data type, the returned array must have the default complex floating-point data type. - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. @@ -49,8 +51,10 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - if ``include_initial`` is ``True``, + - if ``N`` is greater than zero, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - if ``N`` is zero (i.e., ``x`` is an empty array), the returned array must have the same shape as ``x``. + - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes From 756fc92a345a48874a857796e6a6013276e358d9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 18 Oct 2023 18:12:44 -0700 Subject: [PATCH 5/5] Ensure consistent rules for when `include_initial` is `True` --- src/array_api_stubs/_draft/statistical_functions.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 81a124b0d..2b3758e01 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -50,11 +50,7 @@ def cumulative_sum( Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: - - if ``include_initial`` is ``True``, - - - if ``N`` is greater than zero, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - - if ``N`` is zero (i.e., ``x`` is an empty array), the returned array must have the same shape as ``x``. - + - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. Notes pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy