Ctrl+K

unique_values#

ivy.unique_values(x, /, *, out=None)[source]#

Return the unique elements of an input array x.

Data-dependent output shape

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 data-dependent-output-shapes section for more details.

Note

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.

  • As nan values compare as False, nan values should be considered distinct.

  • 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).

Parameters:

  • x (Union[Array, NativeArray]) – input array. If x has more than one dimension, the function must flatten x and return the unique elements of the flattened array.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – 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 unique elements is not specified and may vary between implementations.

Raises:

TypeError – If x is not an instance of ivy.Array or ivy.NativeArray.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

With ivy.Array inputs:

>>> import ivy
>>> a = ivy.array([1, 1, 2, 2, 3, 4, 4, 5])
>>> ivy.unique_values(a)
array([1, 2, 3, 4, 5])

>>> b = ivy.array([1, 2, 3, 4, 5])
>>> ivy.unique_values(b)
array([1, 2, 3, 4, 5])

>>> c = ivy.array([1.0, 1.0, 2.0, 2.0, 3.0, 4.0, 4.0, 5.0, -0.0, 0.0, float('nan'),
...                float('nan')])
>>> ivy.unique_values(c)
array([0., 1., 2., 3., 4., 5., nan, -0.])
Array.unique_values(self, /, *, out=None)[source]#

Return the unique elements of an input array x. .. admonition:: Data-dependent output shape

class:

important

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 data-dependent-output-shapes section for more details.

Note

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. - As nan values compare as False, nan values

should be considered distinct.

  • 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).

Parameters:

  • x (ivy.Array or ivy.NativeArray) – Input array. If x has more than one dimension, the function must flatten x and return the unique elements of the flattened array.

  • out (ivy.Array, optional) – Optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ivy.Array – 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 unique elements is not specified and may vary
between implementations.

Raises:

TypeError – If x is not an instance of ivy.Array or ivy.NativeArray.

Examples

>>> import ivy
>>> x = ivy.array([1, 2, 2, 3, 4, 4, 4])
>>> print(x.unique_values())
ivy.array([1, 2, 3, 4])

>>> x = ivy.array([[1, 2], [3, 4]])
>>> print(x.unique_values())
ivy.array([1, 2, 3, 4])
Container.unique_values(self, /, *, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

ivy.Container instance method variant of ivy.unique_values. This method simply wraps the function and applies it on the container.

Parameters:

  • self (ivy.Container) – input container

  • key_chains (list or dict, optional) – The key-chains to apply or not apply the method to. Default is None.

  • to_apply (bool, optional) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.

  • prune_unapplied (bool, optional) – Whether to prune key_chains for which the function was not applied. Default is False.

  • map_sequences (bool, optional) – Whether to also map method to sequences (lists, tuples). Default is False.

  • out (ivy.Container, optional) – The container to return the results in. Default is None.

Return type:

Container

Returns:

ivy.Container – The result container with the unique values for each input key-chain.

Raises:

  • TypeError – If the input container is not an instance of ivy.Container.

  • ValueError – If the key_chains parameter is not None, and it is not a list or a dictionary.

Example

>>> x = ivy.Container(a=[1, 2, 3], b=[2, 2, 3], c=[4, 4, 4])
>>> y = x.unique_values()
>>> print(y)
{
    a: ivy.array([1, 2, 3]),
    b: ivy.array([2, 3]),
    c: ivy.array([4])
}

>>> x = ivy.Container(a=[1, 2, 3], b=[2, 2, 3], c=[4, 4, 4])
>>> y = x.unique_values(key_chains=["a", "b"])
>>> print(y)
{
    a: ivy.array([1, 2, 3]),
    b: ivy.array([2, 3]),
    c: [
        4,
        4,
        4
    ]
}
On this page