From c887a0b6c305af7b17e64568e71c1951a246921f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 27 Sep 2021 11:41:06 -0700 Subject: [PATCH 1/6] Split `unique` into separate functions --- spec/API_specification/set_functions.md | 68 +++++++++++++++++-------- 1 file changed, 47 insertions(+), 21 deletions(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index e00b116f9..6ef9e0d4a 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -13,12 +13,12 @@ A conforming implementation of the array API standard must provide and support t (function-unique)= -### unique(x, /, *, return_counts=False, return_index=False, return_inverse=False) +### unique(x, /) :::{admonition} Data-dependent output shape :class: important -The shapes of one or more of output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. +The shapes of one of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. ::: Returns the unique elements of an input array `x`. @@ -29,40 +29,66 @@ Returns the unique elements of an input array `x`. - 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_ +#### Returns + +- **out**: _Tuple\[ <array>, <array>, <array>, <array> ]_ + + - a namedtuple `(values, indices, inverse_indices, counts)` whose + + - first element must have the field name `values` and must be an array containing the unique elements of `x`. + - second element must have the field name `indices` and must be an array containing the indices (first occurrences) of `x` that result in `values`. The array must have the same shape as `values` and must have the default integer data type. + - third element must have the field name `inverse_indices` and must be an array containing the indices of `values` that reconstruct `x`. The array must have the same shape as `x` and must have the default integer data type. + - fourth element must have the field name `counts` and must be an array containing the number of times each unique element occurs in `x`. The returned array must have same shape as `x` and must have the default integer data type. + +(function-unique-inverse)= +### unique_inverse(x, /) + +Returns the unique elements of an input array `x` and the indices from the set of unique elements that reconstruct `x`. - - If `True`, the function must also return the number of times each unique element occurs in `x`. Default: `False`. +:::{admonition} Data-dependent output shape +:class: important -- **return_index**: _bool_ +The shape of one of the output arrays for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. +::: - - If `True`, the function must also return the indices (first occurrences) of `x` that result in the unique array. Default: `False`. +#### Parameters -- **return_inverse**: _bool_ +- **x**: _<array>_ - - If `True`, the function must also return the indices of the unique array that reconstruct `x`. Default: `False`. + - input array. If `x` has more than one dimension, the function must flatten `x` and return the unique elements of the flattened array. #### Returns -- **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_ +- **out**: _Tuple\[ <array>, <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): + - a namedtuple `(values, inverse_indices)` whose - - **unique**: _<array>_ + - first element must have the field name `values` and must be an array containing the unique elements of `x`. + - second element must have the field name `inverse_indices` and must be an array containing the indices of `values` that reconstruct `x`. The array must have the same shape as `x` and have the default integer data type. - - an array containing the set of unique elements in `x`. The returned array must have the same data type as `x`. +(function-unique-values)= +### unique_values(x, /) - ```{note} - The order of elements is not specified, and may vary between implementations. - ``` +:::{admonition} Data-dependent output shape +:class: important + +The shape of the output array for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. +::: - - **indices**: _<array>_ +Returns the unique elements of an input array `x`. - - an array containing the indices (first occurrences) of `x` that result in `unique`. The returned array must have the default integer data type. +#### Parameters - - **inverse**: _<array>_ +- **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. + +#### Returns - - an array containing the indices of `unique` that reconstruct `x`. The returned array must have the default integer data type. +- **out**: _<array>_ - - **counts**: _<array>_ + - an array containing the set of unique elements in `x`. The returned array must have the same data type as `x`. - - an array containing the number of times each unique element occurs in `x`. The returned array must have the default integer data type. + ```{note} + The order of elements is not specified and may vary between implementations. + ``` \ No newline at end of file From cba2ff12ef2a12902f447d6ce63d3985a0204bdd Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 27 Sep 2021 11:51:18 -0700 Subject: [PATCH 2/6] Update copy --- spec/API_specification/set_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index 6ef9e0d4a..cf7d0697b 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -18,7 +18,7 @@ A conforming implementation of the array API standard must provide and support t :::{admonition} Data-dependent output shape :class: important -The shapes of one of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. +The shapes of two of the output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details. ::: Returns the unique elements of an input array `x`. From c902f09067654b2554dbd31721f63e038841a6e3 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 27 Sep 2021 11:52:35 -0700 Subject: [PATCH 3/6] Fix shape guidance --- spec/API_specification/set_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index cf7d0697b..799398ade 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -38,7 +38,7 @@ Returns the unique elements of an input array `x`. - first element must have the field name `values` and must be an array containing the unique elements of `x`. - second element must have the field name `indices` and must be an array containing the indices (first occurrences) of `x` that result in `values`. The array must have the same shape as `values` and must have the default integer data type. - third element must have the field name `inverse_indices` and must be an array containing the indices of `values` that reconstruct `x`. The array must have the same shape as `x` and must have the default integer data type. - - fourth element must have the field name `counts` and must be an array containing the number of times each unique element occurs in `x`. The returned array must have same shape as `x` and must have the default integer data type. + - fourth element must have the field name `counts` and must be an array containing the number of times each unique element occurs in `x`. The returned array must have same shape as `values` and must have the default integer data type. (function-unique-inverse)= ### unique_inverse(x, /) From eab2cbbc64b0fef78008483bfdb3806ab9dcdabc Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 27 Sep 2021 11:54:09 -0700 Subject: [PATCH 4/6] Add notes --- spec/API_specification/set_functions.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index 799398ade..9b4a366d2 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -40,6 +40,10 @@ Returns the unique elements of an input array `x`. - third element must have the field name `inverse_indices` and must be an array containing the indices of `values` that reconstruct `x`. The array must have the same shape as `x` and must have the default integer data type. - fourth element must have the field name `counts` and must be an array containing the number of times each unique element occurs in `x`. The returned array must have same shape as `values` and must have the default integer data type. + ```{note} + The order of unique elements is not specified and may vary between implementations. + ``` + (function-unique-inverse)= ### unique_inverse(x, /) @@ -66,6 +70,10 @@ The shape of one of the output arrays for this function depends on the data valu - first element must have the field name `values` and must be an array containing the unique elements of `x`. - second element must have the field name `inverse_indices` and must be an array containing the indices of `values` that reconstruct `x`. The array must have the same shape as `x` and have the default integer data type. + ```{note} + The order of unique elements is not specified and may vary between implementations. + ``` + (function-unique-values)= ### unique_values(x, /) @@ -90,5 +98,5 @@ Returns the unique elements of an input array `x`. - an array containing the set of unique elements in `x`. The returned array must have the same data type as `x`. ```{note} - The order of elements is not specified and may vary between implementations. + The order of unique elements is not specified and may vary between implementations. ``` \ No newline at end of file From 4485d692f1f400be07f66627ac597f5e8a66945e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 4 Oct 2021 09:41:16 -0700 Subject: [PATCH 5/6] Rename function to avoid breaking backward compat --- spec/API_specification/set_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index 9b4a366d2..9160bbd6a 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -12,8 +12,8 @@ A conforming implementation of the array API standard must provide and support t -(function-unique)= -### unique(x, /) +(function-unique-all)= +### unique_all(x, /) :::{admonition} Data-dependent output shape :class: important From 6ef55f24fa56b0f602ff52b513bfbeddc706a8e6 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Wed, 20 Oct 2021 17:39:53 -0700 Subject: [PATCH 6/6] Specify the `values` array data type --- spec/API_specification/set_functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/set_functions.md b/spec/API_specification/set_functions.md index 9160bbd6a..3f3a9d192 100644 --- a/spec/API_specification/set_functions.md +++ b/spec/API_specification/set_functions.md @@ -35,7 +35,7 @@ Returns the unique elements of an input array `x`. - a namedtuple `(values, indices, inverse_indices, counts)` whose - - first element must have the field name `values` and must be an array containing the unique elements of `x`. + - first element must have the field name `values` and must be an array containing the unique elements of `x`. The array must have the same data type as `x`. - second element must have the field name `indices` and must be an array containing the indices (first occurrences) of `x` that result in `values`. The array must have the same shape as `values` and must have the default integer data type. - third element must have the field name `inverse_indices` and must be an array containing the indices of `values` that reconstruct `x`. The array must have the same shape as `x` and must have the default integer data type. - fourth element must have the field name `counts` and must be an array containing the number of times each unique element occurs in `x`. The returned array must have same shape as `values` and must have the default integer data type. @@ -67,7 +67,7 @@ The shape of one of the output arrays for this function depends on the data valu - a namedtuple `(values, inverse_indices)` whose - - first element must have the field name `values` and must be an array containing the unique elements of `x`. + - first element must have the field name `values` and must be an array containing the unique elements of `x`. The array must have the same data type as `x`. - second element must have the field name `inverse_indices` and must be an array containing the indices of `values` that reconstruct `x`. The array must have the same shape as `x` and have the default integer data type. ```{note}