From 3bd3574e440ac79036a6051c128d55982b8e9a02 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Sun, 5 Nov 2023 20:53:59 -0800 Subject: [PATCH] fix: clarify flattening behavior and fix required shape of `inverse_indices` This commit backports the following changes to the 2021 and 2022 revisions of the Array API standard: - correction to the required output shape of `inverse_indices`. Prior revisions stated that this should have the same shape as `x`, but this is only true if `x` is one-dimensional. For multi-dimensional `x`, the output shape should the size of a flattened `x`. - clarifications regarding the contents of returned indices (first occurrences). Namely, that the returned array should include indices into a flattened `x`. For the case where `x` is one-dimensional, the guidance is the same. For multi-dimensional `x`, this clarifies that returned indices are for the flattened `x` and not the original input array. --- src/array_api_stubs/_2021_12/set_functions.py | 6 +++--- src/array_api_stubs/_2022_12/set_functions.py | 6 +++--- src/array_api_stubs/_draft/set_functions.py | 18 +++++++++--------- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/array_api_stubs/_2021_12/set_functions.py b/src/array_api_stubs/_2021_12/set_functions.py index eb5c1d951..20a2bb594 100644 --- a/src/array_api_stubs/_2021_12/set_functions.py +++ b/src/array_api_stubs/_2021_12/set_functions.py @@ -32,8 +32,8 @@ def unique_all(x: array, /) -> 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``. 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 array index 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 array index data type. + - second element must have the field name ``indices`` and must be an array containing the indices (first occurrences) of a flattened ``x`` that result in ``values``. The array must have the same shape as ``values`` and must have the default array index data type. + - third element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct a flattened ``x``. The array must have the same shape as a flattened ``x`` and must have the default array index 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 array index data type. .. note:: @@ -104,7 +104,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: 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``. 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 array index data type. + - second element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct a flattened ``x``. The array must have the same shape as a flattened ``x`` and have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. diff --git a/src/array_api_stubs/_2022_12/set_functions.py b/src/array_api_stubs/_2022_12/set_functions.py index 661d3df90..fbc4263f5 100644 --- a/src/array_api_stubs/_2022_12/set_functions.py +++ b/src/array_api_stubs/_2022_12/set_functions.py @@ -32,8 +32,8 @@ def unique_all(x: array, /) -> 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``. 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 array index 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 array index data type. + - second element must have the field name ``indices`` and must be an array containing the indices (first occurrences) of a flattened ``x`` that result in ``values``. The array must have the same shape as ``values`` and must have the default array index data type. + - third element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct a flattened ``x``. The array must have the same shape as a flattened ``x`` and must have the default array index 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 array index data type. .. note:: @@ -118,7 +118,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: 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``. 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 array index data type. + - second element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct a flattened ``x``. The array must have the same shape as a flattened ``x`` and have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. diff --git a/src/array_api_stubs/_draft/set_functions.py b/src/array_api_stubs/_draft/set_functions.py index 394fa2b17..16173650b 100644 --- a/src/array_api_stubs/_draft/set_functions.py +++ b/src/array_api_stubs/_draft/set_functions.py @@ -27,7 +27,7 @@ def unique_all(x: array, /) -> Tuple[array, array, array, array]: 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. + input array. If ``x`` has more than one dimension, the function must flatten ``x`` in row-major, C-style order and return the unique elements of the flattened array. Returns ------- @@ -35,9 +35,9 @@ def unique_all(x: array, /) -> 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``. 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 array index 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 array index 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 array index data type. + - second element must have the field name ``indices`` and must be an array containing the indices (first occurrences) of a flattened ``x`` that result in ``values``. The array must have the same shape as ``values`` and must have the default array index data type. + - third element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct a flattened ``x``. The array must have the same shape as a flattened ``x`` and must have the default array index 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 order of the returned counts must match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array must have same shape as ``values`` and must have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. @@ -71,7 +71,7 @@ def unique_counts(x: array, /) -> Tuple[array, array]: 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. + input array. If ``x`` has more than one dimension, the function must flatten ``x`` in row-major, C-style order and return the unique elements of the flattened array. Returns ------- @@ -79,7 +79,7 @@ def unique_counts(x: array, /) -> Tuple[array, array]: a namedtuple `(values, counts)` whose - 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 `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 array index data type. + - second element must have the field name `counts` and must be an array containing the number of times each unique element occurs in ``x``. The order of the returned counts must match the order of ``values``, such that a specific element in ``counts`` corresponds to the respective unique element in ``values``. The returned array must have same shape as ``values`` and must have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. @@ -113,7 +113,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: 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. + input array. If ``x`` has more than one dimension, the function must flatten ``x`` in row-major, C-style order and return the unique elements of the flattened array. Returns ------- @@ -121,7 +121,7 @@ def unique_inverse(x: array, /) -> Tuple[array, array]: 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``. 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 array index data type. + - second element must have the field name ``inverse_indices`` and must be an array containing the indices of ``values`` that reconstruct a flattened ``x``. The array must have the same shape as a flattened ``x`` and have the default array index data type. .. note:: The order of unique elements is not specified and may vary between implementations. @@ -153,7 +153,7 @@ def unique_values(x: array, /) -> array: 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. + input array. If ``x`` has more than one dimension, the function must flatten ``x`` in row-major, C-style order and return the unique elements of the flattened array. Returns -------