# top_k#

ivy.top_k(x, k, /, *, axis=-1, largest=True, sorted=True, out=None)[source]#

Return the k largest elements of the given input array along a given axis.

Parameters:
• x (`Union`[`Array`, `NativeArray`]) – The array to compute top_k for.

• k (`int`) – Number of top elements to return must not exceed the array size.

• axis (`int`, default: `-1`) – The axis along which we must return the top elements default value is 1.

• largest (`bool`, default: `True`) – If largest is set to False we return k smallest elements of the array.

• sorted (`bool`, default: `True`) – If sorted is set to True we return the elements in sorted order.

• out (`Optional`[`tuple`], default: `None`) – Optional output tuple, for writing the result to. Must have two arrays inside, with a shape that the returned tuple broadcast to.

Return type:

`Tuple`[`Array`, `NativeArray`]

Returns:

ret – A named tuple with values and indices of top k elements.

Examples

With `ivy.Array` input:

```>>> x = ivy.array([2., 1., -3., 5., 9., 0., -4])
>>> y = ivy.top_k(x, 2)
>>> print(y)
top_k(values=ivy.array([9., 5.]), indices=ivy.array([4, 3]))
```
```>>> x = ivy.array([[-2., 3., 4., 0.], [-8., 0., -1., 2.]])
>>> y = ivy.top_k(x, 2, axis=1, largest=False)
>>> print(y)
top_k(values=ivy.array([[-2.,  0.],
[-8., -1.]]), indices=ivy.array([[0, 3],
[0, 2]]))
```

With `ivy.NativeArray` input:

```>>> x = ivy.native_array([2., 1., -3., 5., 9., 0., -4])
>>> y = ivy.top_k(x, 3)
>>> print(y)
top_k(values=ivy.array([9., 5., 2.]), indices=ivy.array([4, 3, 0]))
```

With `ivy.Container` input:

```>>> x = ivy.Container(a=ivy.array([-1, 2, -4]), b=ivy.array([4., 5., 0.]))
>>> y = x.top_k(2)
>>> print(y)
[{
a: ivy.array([2, -1]),
b: ivy.array([5., 4.])
}, {
a: ivy.array([1, 0]),
b: ivy.array([1, 0])
}]
```
Array.top_k(self, k, /, *, axis=-1, largest=True, sorted=True, out=None)[source]#

ivy.Array instance method variant of ivy.top_k. This method simply wraps the function, and so the docstring for ivy.top_k also applies to this method with minimal changes.

Parameters:
• self (`Array`) – The array to compute top_k for.

• k (`int`) – Number of top elements to return must not exceed the array size.

• axis (`int`, default: `-1`) – The axis along which we must return the top elements default value is 1.

• largest (`bool`, default: `True`) – If largest is set to False we return k smallest elements of the array.

• sorted (`bool`, default: `True`) – If sorted is set to True we return the elements in sorted order.

• out (`Optional`[`tuple`], default: `None`) – Optional output tuple, for writing the result to. Must have two arrays, with a shape that the returned tuple broadcast to.

Return type:

`Tuple`[`Array`, `NativeArray`]

Returns:

ret – A named tuple with values and indices of top k elements.

Examples

With `ivy.Array` input:

```>>> x = ivy.array([2., 1., -3., 5., 9., 0., -4])
>>> y = x.top_k(2)
>>> print(y)
top_k(values=ivy.array([9., 5.]), indices=ivy.array([4, 3]))
```
Container.top_k(self, k, /, *, axis=-1, largest=True, sorted=True, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

ivy.Container instance method variant of ivy.top_k. This method simply wraps the function, and so the docstring for ivy.top_k also applies to this method with minimal changes.

Parameters:
• self (`Container`) – The container to compute top_k for.

• k (`Union`[`int`, `Container`]) – Number of top elements to return must not exceed the array size.

• axis (`Union`[`int`, `Container`], default: `-1`) – The axis along which we must return the top elements default value is 1.

• largest (`Union`[`bool`, `Container`], default: `True`) – If largest is set to False we return k smallest elements of the array.

• sorted (`Union`[`bool`, `Container`], default: `True`) – If sorted is set to True we return the elements in sorted order.

• key_chains (`Optional`[`Union`[`List`[`str`], `Dict`[`str`, `str`], `Container`]], default: `None`) – The key-chains to apply or not apply the method to. Default is `None`.

• to_apply (`Union`[`bool`, `Container`], default: `True`) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is `True`.

• prune_unapplied (`Union`[`bool`, `Container`], default: `False`) – Whether to prune key_chains for which the function was not applied. Default is `False`.

• map_sequences (`Union`[`bool`, `Container`], default: `False`) – Whether to also map method to sequences (lists, tuples). Default is `False`

• out (`Optional`[`Tuple`[`Container`, `Container`]], default: `None`) – Optional output tuple, for writing the result to. Must have two Container, with a shape that the returned tuple broadcast to.

Return type:

`Tuple`[`Container`, `Container`]

Returns:

ret – a container with indices and values.

Examples

With `ivy.Container` input:

```>>> x = ivy.Container(a=ivy.array([-1, 2, -4]), b=ivy.array([4., 5., 0.]))
>>> y = x.top_k(2)
>>> print(y)
[{
a: ivy.array([2, -1]),
b: ivy.array([5., 4.])
}, {
a: ivy.array([1, 0]),
b: ivy.array([1, 0])
}]
```