Skip to content

Commit b6f5ad7

Browse files
leofangkgryte
andauthored
Add unique_counts() and fix the description of unique_all() (#317)
* add unique_counts and a few fixes * fix typo * defer the discussion on index type promotion to another PR * Update note * Update type annotation Co-authored-by: Athan <kgryte@gmail.com>
1 parent 65305a4 commit b6f5ad7

File tree

1 file changed

+41
-2
lines changed

1 file changed

+41
-2
lines changed

spec/API_specification/set_functions.md

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ A conforming implementation of the array API standard must provide and support t
2121
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.
2222
:::
2323

24-
Returns the unique elements of an input array `x`.
24+
Returns the unique elements of an input array `x`, the first occurring indices for each unique element in `x`, the indices from the set of unique elements that reconstruct `x`, and the corresponding counts for each unique element in `x`.
2525

2626
```{note}
2727
Uniqueness should be determined based on value equality (i.e., `x_i == x_j`). For input arrays having floating-point data types, value-based equality implies the following behavior.
@@ -55,6 +55,45 @@ Each `nan` value should have a count of one, while the counts for signed zeros s
5555
The order of unique elements is not specified and may vary between implementations.
5656
```
5757
58+
(function-unique-counts)=
59+
### unique_counts(x, /)
60+
61+
:::{admonition} Data-dependent output shape
62+
:class: important
63+
64+
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.
65+
:::
66+
67+
Returns the unique elements of an input array `x` and the corresponding counts for each unique element in `x`.
68+
69+
```{note}
70+
Uniqueness should be determined based on value equality (i.e., `x_i == x_j`). For input arrays having floating-point data types, value-based equality implies the following behavior.
71+
72+
- As `nan` values compare as `False`, `nan` values should be considered distinct.
73+
- As `-0` and `+0` compare as `True`, signed zeros should not be considered distinct, and the corresponding unique element will be implementation-dependent (e.g., an implementation could choose to return `-0` if `-0` occurs before `+0`).
74+
75+
Each `nan` value should have a count of one, while the counts for signed zeros should be aggregated as a single count.
76+
```
77+
78+
#### Parameters
79+
80+
- **x**: _&lt;array&gt;_
81+
82+
- input array. If `x` has more than one dimension, the function must flatten `x` and return the unique elements of the flattened array.
83+
84+
#### Returns
85+
86+
- **out**: _Tuple\[ &lt;array&gt;, &lt;array&gt; ]_
87+
88+
- a namedtuple `(values, counts)` whose
89+
90+
- 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`.
91+
- 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 integer data type.
92+
93+
```{note}
94+
The order of unique elements is not specified and may vary between implementations.
95+
```
96+
5897
(function-unique-inverse)=
5998
### unique_inverse(x, /)
6099
@@ -126,4 +165,4 @@ Uniqueness should be determined based on value equality (i.e., `x_i == x_j`). Fo
126165

127166
```{note}
128167
The order of unique elements is not specified and may vary between implementations.
129-
```
168+
```

0 commit comments

Comments
 (0)