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]]) – if bins is an int, it defines the number of equal-width bins in the given (default: None) 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]) – dimension along which maximum values must be computed. By default, the maximum (default: None) value must be computed over the entire array. Default: None.

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

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

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

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

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

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

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) 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]), ivy.array([0. , 0.5, 1. , 1.5, 2. ]))

>>> 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([0, 0, 0, 0]), ivy.array([0.   , 0.125, 0.25 , 0.375, 0.5  ]))

>>> 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.]]), ivy.array([0., 1., 2., 3., 4., 5.]))

>>> 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)
>>> print(z.b)
(ivy.array([1, 1, 1, 0, 0]), ivy.array([0., 1., 2., 3., 4., 5.]))
(ivy.array([0, 0, 0, 1, 2]), ivy.array([0., 1., 2., 3., 4., 5.]))
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)#

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]]) – if bins is an int, it defines the number of equal-width bins in the (default: None) 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]]) – dimension along which maximum values must be computed. By default, the (default: None) maximum value must be computed over the entire array. Default: None.

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

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

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

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

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

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

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that (default: None) 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]), ivy.array([0. , 0.5, 1. , 1.5, 2. ]))
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)#

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]]) – if bins is an int, it defines the number of equal-width bins in the (default: None) 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]]) – dimension along which maximum values must be computed. By default, the (default: None) maximum value must be computed over the entire array. Default: None.

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

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

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

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

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

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

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

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

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

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

  • out (Optional[Container]) – optional output, for writing the result to. It must have a shape that the (default: None) 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 = ivy.histogram(x, bins=y, dtype=dtype)
>>> print(z.a)
>>> print(z.b)
(ivy.array([1, 1, 1, 0, 0]), ivy.array([0., 1., 2., 3., 4., 5.]))
(ivy.array([0, 0, 0, 1, 2]), ivy.array([0., 1., 2., 3., 4., 5.]))