From 9d426a16ac5bef6cada253c7b819abb9f2989291 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 26 Aug 2020 13:07:13 -0700 Subject: [PATCH 1/3] Add `unique` signature --- spec/API_specification/set_functions.md | 55 +++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 spec/API_specification/set_functions.md diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md new file mode 100644 index 000000000..fa34993d5 --- /dev/null +++ b/spec/API_specification/set_functions.md @@ -0,0 +1,55 @@ +# Set Functions + +> Array API specification for creating and operating on sets. + +A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. + +- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. +- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. + + + +### # unique(x, /, *, return_counts=False, return_index=False, return_inverse=False) + +Returns the unique elements of an input array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array. If `x` has more than one dimension, the function must flatten `x` and return the unique elements of the flattened array. + +- **return_counts**: _bool_ + + - If `True`, the function must also return the number of times each unique element occurs in `x`. Default: `False`. + +- **return_index**: _bool_ + + - If `True`, the function must also return the indices (first occurrences) of `x` that result in the unique array. Default: `False`. + +- **return_inverse**: _bool_ + + - If `True`, the function must also return the indices of the unique array that reconstruct `x`. Default: `False`. + +#### Returns + +- **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ + + - if `return_counts`, `return_index`, and `return_inverse` are all `False`, an array containing the set of unique elements in `x`; otherwise, a tuple containing two or more of the following arrays (in order): + + - **unique**: _<array>_ + + - an array containing the set of unique elements in `x`. + + - **indices**: _<array>_ + + - an array containing the indices (first occurrences) of `x` that result in `unique`. + + - **inverse**: _<array>_ + + - an array containing the indices of `unique` that reconstruct `x`. + + - **counts**: _<array>_ + + - an array containing the number of times each unique element occurs in `x`. \ No newline at end of file From 9311d91a3e6f38cb13f079226445102a978071c7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 26 Aug 2020 13:07:34 -0700 Subject: [PATCH 2/3] Update index --- spec/API_specification/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index 72aac7729..1cde34b0d 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -14,3 +14,4 @@ API specification out_keyword elementwise_functions statistical_functions + set_functions \ No newline at end of file From cec9cd2bc8d92dcdd600d140a5c3227cfccd104e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 14 Sep 2020 01:39:14 -0700 Subject: [PATCH 3/3] Add TODO --- spec/API_specification/set_functions.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index fa34993d5..c147388fc 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -10,7 +10,7 @@ A conforming implementation of the array API standard must provide and support t -### # unique(x, /, *, return_counts=False, return_index=False, return_inverse=False) +### # unique(x, /, *, return_counts=False, return_index=False, return_inverse=False, sorted=True) Returns the unique elements of an input array `x`. @@ -32,6 +32,12 @@ Returns the unique elements of an input array `x`. - If `True`, the function must also return the indices of the unique array that reconstruct `x`. Default: `False`. +- **sorted**: _bool_ + + - If `True`, the function must sort the unique elements in ascending order before returning as output. If `False`, the function must sort the unique elements in the same order that they occur in `x`. Default: `False`. + + _TODO: sort order needs discussion. See [gh-40](https://github.com/data-apis/array-api/issues/40)_ + #### Returns - **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_