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])
}