# histogram#

ivy.histogram(a, /, *, bins=None, axis=None, extend_lower_interval=False, extend_upper_interval=False, dtype=None, range=None, weights=None, density=False, out=None)[source]#

Compute the histogram of the array `a`.

Note

Given bins = [c0, …, cK], defining intervals I0 = [c0, c1), I1 = [c1, c2), …, I_{K-1} = [c_{K-1}, cK].

Parameters:
• a (`Union`[`Array`, `NativeArray`]) – input array.

• bins (`Optional`[`Union`[`int`, `Array`, `NativeArray`]], default: `None`) – if `bins` is an int, it defines the number of equal-width bins in the given range. if `bins` is an array, it defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths.

• axis (`Optional`[`int`], default: `None`) – dimension along which maximum values must be computed. By default, the maximum value must be computed over the entire array. Default: `None`.

• extend_lower_interval (`Optional`[`bool`], default: `False`) – if True, extend the lowest interval I0 to (-inf, c1].

• extend_upper_interval (`Optional`[`bool`], default: `False`) – ff True, extend the upper interval I_{K-1} to [c_{K-1}, +inf).

• dtype (`Optional`[`Union`[`Dtype`, `NativeDtype`]], default: `None`) – the output type.

• range (`Optional`[`Tuple`[`float`]], default: `None`) – the lower and upper range of the bins. The first element of the range must be less than or equal to the second.

• weights (`Optional`[`Union`[`Array`, `NativeArray`]], default: `None`) – each value in `a` only contributes its associated weight towards the bin count (instead of 1). Must be of the same shape as a.

• density (`Optional`[`bool`], default: `False`) – if True, the result is the value of the probability density function at the bin, normalized such that the integral over the range of bins is 1.

• 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 – a tuple containing the values of the histogram and the bin edges.

• 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` input:

```>>> x = ivy.array([0, 1, 2])
>>> y = ivy.array([0., 0.5, 1., 1.5, 2.])
>>> z = ivy.histogram(x, bins=y)
>>> print(z)
ivy.array([1., 0., 1., 1.])
```
```>>> x = ivy.array([[1.1, 2.2, 3.3],
...                [4.4, 5.5, .6]])
>>> bins = 4
>>> range = (0., 5.)
>>> dtype = ivy.int32
>>> y = ivy.histogram(x, bins=bins, range=range, dtype=dtype)
>>> print(y)
ivy.array([2, 1, 1, 1])
```
```>>> x = ivy.array([[1.1, 2.2, 3.3],
...                [-4.4, -5.5, -6.6]])
>>> y = ivy.array([0., 1., 2., 3., 4., 5.])
>>> axis = 1
>>> extend_lower_interval = True
>>> extend_upper_interval = True
>>> dtype = ivy.float32
>>> weights = ivy.array([[1., 1., 1.], [1., 1., 1.]])
>>> z = ivy.histogram(
...                     x,
...                     bins=y,
...                     axis=axis,
...                     extend_lower_interval=extend_lower_interval,
...                     extend_upper_interval=extend_upper_interval,
...                     dtype=dtype,
...                     weights=weights)
>>> print(z)
ivy.array([[0., 3.],
[1., 0.],
[1., 0.],
[1., 0.],
[0., 0.]])
```
```>>> x = ivy.Container(a=ivy.array([0., 1., 2.]), b=ivy.array([3., 4., 5.]))
>>> y = ivy.array([0., 1., 2., 3., 4., 5.])
>>> dtype = ivy.int32
>>> z = ivy.histogram(x, bins=y, dtype=dtype)
>>> print(z)
{
a: ivy.array([1, 1, 1, 0, 0]),
b: ivy.array([0, 0, 0, 1, 2])
}
```
Array.histogram(self, /, *, bins=None, axis=None, extend_lower_interval=False, extend_upper_interval=False, dtype=None, range=None, weights=None, density=False, out=None)[source]#

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

Parameters:
• self (`Array`) – input array.

• bins (`Optional`[`Union`[`int`, `Array`, `NativeArray`, `str`]], default: `None`) – if `bins` is an int, it defines the number of equal-width bins in the given range. if `bins` is an array, it defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths.

• axis (`Optional`[`Union`[`Array`, `NativeArray`]], default: `None`) – dimension along which maximum values must be computed. By default, the maximum value must be computed over the entire array. Default: `None`.

• extend_lower_interval (`Optional`[`bool`], default: `False`) – if True, extend the lowest interval I0 to (-inf, c1].

• extend_upper_interval (`Optional`[`bool`], default: `False`) – ff True, extend the upper interval I_{K-1} to [c_{K-1}, +inf).

• dtype (`Optional`[`Union`[`Dtype`, `NativeDtype`]], default: `None`) – the output type.

• range (`Optional`[`Tuple`[`float`]], default: `None`) – the lower and upper range of the bins. The first element of the range must be less than or equal to the second.

• weights (`Optional`[`Union`[`Array`, `NativeArray`]], default: `None`) – each value in `a` only contributes its associated weight towards the bin count (instead of 1). Must be of the same shape as a.

• density (`Optional`[`bool`], default: `False`) – if True, the result is the value of the probability density function at the bin, normalized such that the integral over the range of bins is 1.

• 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 – a tuple containing the values of the histogram and the bin edges.

• 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` input:

```>>> x = ivy.array([0, 1, 2])
>>> y = ivy.array([0., 0.5, 1., 1.5, 2.])
>>> z = ivy.histogram(x, bins=y)
>>> print(z)
ivy.array([1., 0., 1., 1.])
```
Container.histogram(self, /, *, bins=None, axis=None, extend_lower_interval=False, extend_upper_interval=False, dtype=None, range=None, weights=None, density=False, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

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

Parameters:
• self (`Container`) – input array.

• bins (`Optional`[`Union`[`int`, `Array`, `NativeArray`, `Container`, `str`]], default: `None`) – if `bins` is an int, it defines the number of equal-width bins in the given range. if `bins` is an array, it defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths.

• axis (`Optional`[`Union`[`Array`, `NativeArray`, `Container`]], default: `None`) – dimension along which maximum values must be computed. By default, the maximum value must be computed over the entire array. Default: `None`.

• extend_lower_interval (`Optional`[`Union`[`bool`, `Container`]], default: `False`) – if True, extend the lowest interval I0 to (-inf, c1].

• extend_upper_interval (`Optional`[`Union`[`bool`, `Container`]], default: `False`) – ff True, extend the upper interval I_{K-1} to [c_{K-1}, +inf).

• dtype (`Optional`[`Union`[`Dtype`, `NativeDtype`, `Container`]], default: `None`) – the output type.

• range (`Optional`[`Union`[`Tuple`[`float`], `Container`]], default: `None`) – the lower and upper range of the bins. The first element of the range must be less than or equal to the second.

• weights (`Optional`[`Union`[`Array`, `NativeArray`, `Container`]], default: `None`) – each value in `a` only contributes its associated weight towards the bin count (instead of 1). Must be of the same shape as a.

• density (`Optional`[`Union`[`bool`, `Container`]], default: `False`) – if True, the result is the value of the probability density function at the bin, normalized such that the integral over the range of bins is 1.

• 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`[`Container`], default: `None`) – optional output, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

`Container`

Returns:

• ret – a tuple containing the values of the histogram and the bin edges.

• 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.Container` input:

```>>> x = ivy.Container(a=ivy.array([0., 1., 2.]), b=ivy.array([3., 4., 5.]))
>>> y = ivy.array([0., 1., 2., 3., 4., 5.])
>>> dtype = ivy.int32
>>> z = x.histogram(bins=y, dtype=dtype)
>>> print(z)
{
a: ivy.array([1, 1, 1, 0, 0]),
b: ivy.array([0, 0, 0, 1, 2])
}
```