Statistical#

ivy.bincount(x, /, *, weights=None, minlength=0, out=None)[source]#

Count the number of occurrences of each value in an integer array.

Parameters:

self – Input array.
weights (Optional[Array], default: None) – An optional input array.
minlength (int, default: 0) – A minimum number of bins for the output array.

Return type:

Array

Returns:

ret – The bincount of the array elements.

Examples

>>> a = ivy.Container([[10.0, ivy.nan, 4], [3, 2, 1]])
>>> a.bincount(a)
    3.0
>>> a.bincount(a, axis=0)
    array([6.5, 2. , 2.5])

ivy.corrcoef(x, /, *, y=None, rowvar=True, out=None)[source]#

Return type:: Array

ivy.cov(x1, x2=None, /, *, rowVar=True, bias=False, ddof=None, fweights=None, aweights=None, dtype=None)[source]#

Compute the covariance of matrix x1, or variables x1 and x2.

Parameters:

x1 (Union[Array, NativeArray]) – a 1D or 2D input array, with a numeric data type.
x2 (Optional[Union[Array, NativeArray]], default: None) – optional second 1D or 2D input array, with a numeric data type. Must have the same shape as self.
rowVar (bool, default: True) – optional variable where each row of input is interpreted as a variable (default = True). If set to False, each column is instead interpreted as a variable.
bias (bool, default: False) – optional variable for normalizing input (default = False) by (N - 1) where N is the number of given observations. If set to True, then normalization is instead by N. Can be overridden by keyword ddof.
ddof (Optional[int], default: None) – optional variable to override bias (default = None). ddof=1 will return the unbiased estimate, even with fweights and aweights given. ddof=0 will return the simple average.
fweights (Optional[Array], default: None) – optional 1D array of integer frequency weights; the number of times each observation vector should be repeated.
aweights (Optional[Array], default: None) – optional 1D array of observation vector weights. These relative weights are typically large for observations considered “important” and smaller for observations considered less “important”. If ddof=0 is specified, the array of weights can be used to assign probabilities to observation vectors.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – optional variable to set data-type of the result. By default, data-type will have at least numpy.float64 precision.
out – 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 covariance matrix of an input matrix, or the covariance matrix of two variables. The returned array must have a floating-point data type determined by Type Promotion Rules and must be a square matrix of shape (N, N), where N is the number of variables in the input(s).
This function conforms to the `Array API Standard
<https (//data-apis.org/array-api/latest/>`_. This docstring is an extension of the)
`docstring <https (//data-apis.org/array-api/latest/)
extensions/generated/signatures.linalg.cov.html>`_
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 input: >>> x = ivy.array([[1, 2, 3], … [4, 5, 6]]) >>> y = x[0].cov(x[1]) >>> print(y) ivy.array([[1., 1.],

[1., 1.]])

With ivy.Container inputs: >>> x = ivy.Container(a=ivy.array([1., 2., 3.]), b=ivy.array([1., 2., 3.])) >>> y = ivy.Container(a=ivy.array([3., 2., 1.]), b=ivy.array([3., 2., 1.])) >>> z = ivy.Container.static_cov(x, y) >>> print(z) {

a: ivy.array([[1., -1.],
[-1., 1.]]),

b: ivy.array([[1., -1.],
[-1., 1.]])

}

With a combination of ivy.Array and ivy.Container inputs: >>> x = ivy.array([1., 2., 3.]) >>> y = ivy.Container(a=ivy.array([3. ,2. ,1.]), b=ivy.array([-1., -2., -3.])) >>> z = ivy.cov(x, y) >>> print(z) {

a: ivy.array([[1., -1.],
[-1., 1.]]),

b: ivy.array([[1., -1.],
[-1., 1.]])

}

With ivy.Array input and rowVar flag set to False (True by default): >>> x = ivy.array([[1,2,3], … [4,5,6]]) >>> y = x[0].cov(x[1], rowVar=False) >>> print(y) ivy.array([[1., 1.],

[1., 1.]])

With ivy.Array input and bias flag set to True (False by default): >>> x = ivy.array([[1,2,3], … [4,5,6]]) >>> y = x[0].cov(x[1], bias=True) >>> print(y) ivy.array([[0.66666667, 0.66666667],

[0.66666667, 0.66666667]])

With ivy.Array input with both fweights and aweights given: >>> x = ivy.array([[1,2,3], … [4,5,6]]) >>> fw = ivy.array([1,2,3]) >>> aw = ivy.array([ 1.2, 2.3, 3.4 ]) >>> y = x[0].cov(x[1], fweights=fw, aweights=aw) >>> print(y) ivy.array([[0.48447205, 0.48447205],

[0.48447205, 0.48447205]])

ivy.cummax(x, /, *, axis=0, exclusive=False, reverse=False, dtype=None, out=None)[source]#

Return a tuple containing the cumulative maximum of elements of input along the given axis and index location of each maximum value found along the given axis.

Parameters:

x (Union[Array, NativeArray]) – Input array.
axis (int, default: 0) – Axis along which the cumulative maximum is computed. Default is 0.
exclusive (bool, default: False) – Whether to perform cummax exclusively. Default is False.
reverse (bool, default: False) – Whether to perform the cummax from last to first element in the selected axis. Default is False (from first to last element)
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 – Array which holds the result of applying cummax at each original array elements along the specified axis.

Examples

With ivy.Array input:

>>> x = ivy.array([-86, -19, 41, 88, -5, 80, 32, 87, -90, -12])
>>> y = ivy.cummax(x, exclusive=False, reverse=False)
>>> print(y)
(ivy.array([-86, -19,  41,  88,  88,  88,  88,  88,  88,  88]),
ivy.array([0, 1, 2, 3, 3, 3, 3, 3, 3, 3]))

>>> x = ivy.array([ 14,  15,  49, -24, -39])
>>> y = ivy.cummax(x, axis=0, exclusive=False, reverse=False)
>>> print(y)
(ivy.array([14, 15, 49, 49, 49]), ivy.array([0, 1, 2, 2, 2]))

>>> x = ivy.array([[ 63,  43, -16,  -4],[ 21,  82,  59,  33]])
>>> ivy.cummax(x, axis=0, reverse=False, dtype='int64', out=x)
>>> print(x)
ivy.array([[0, 0, 0, 0],
       [0, 1, 1, 1]])

>>> x = ivy.array([[-36,  83, -81],
...                [ 23,  29,  63],
...                [-83,  85,   2],
...                [ 31,  25, -86],
...                [-10, -52,   0],
...                [ 22,  38,  55],
...                [ 33,  54, -16]])
>>> y = ivy.cummax(x, axis=1, exclusive=True, reverse=False)
>>> print(y)
(ivy.array([[ 0,  0, 83],
       [ 0, 23, 29],
       [ 0,  0, 85],
       [ 0, 31, 31],
       [ 0,  0,  0],
       [ 0, 22, 38],
       [ 0, 33, 54]]), ivy.array([[0, 0, 2],
       [0, 1, 2],
       [0, 0, 2],
       [0, 1, 1],
       [0, 0, 0],
       [0, 1, 2],
       [0, 1, 2]]))

>>> x = ivy.array([73, 15, 47])
>>> y = ivy.cummax(x, axis=0, reverse=True, exclusive=True)
>>> print(y)
(ivy.array([47, 47,  0]), ivy.array([0, 0, 0]))

>>> x = ivy.array([-47, -14, -67, 15, -23, -45])
>>> y = ivy.cummax(x, axis=0, reverse=True, exclusive=False)
>>> print(y)
(ivy.array([ 15,  15,  15,  15, -23, -45]), ivy.array([2, 2, 2, 2, 1, 0]))

ivy.cummin(x, /, *, axis=0, exclusive=False, reverse=False, dtype=None, out=None)[source]#

Return the cumulative minimum of the elements along a given axis.

Parameters:

x (Union[Array, NativeArray]) – Input array.
axis (int, default: 0) – Axis along which the cumulative minimum is computed. Default is 0.
reverse (bool, default: False) – Whether to perform the cummin from last to first element in the selected axis. Default is False (from first to last element)
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – Data type of the returned array. Default is None. If None, if the default data type corresponding to the data type “kind” (integer or floating-point) of x has a smaller range of values than the data type of x (e.g., x has data type int64 and the default data type is int32, or x has data type uint64 and the default data type is int64), the returned array must have the same data type as x. If x has a floating-point data type, the returned array must have the default floating-point data type. If x has a signed integer data type (e.g., int16), the returned array must have the default integer data type. If x has an unsigned integer data type (e.g., uint16), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is int32, the returned array must have a uint32 data type). If the data type (either specified or resolved) differs from the data type of x, the input array should be cast to the specified data type before computing the product.
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 – Array which holds the result of applying cummin at each original array elements along the specified axis.

Examples

With ivy.Array input:

>>> x = ivy.array([1, 5, 2, 0])
>>> y = ivy.cummin(x)
>>> print(y)
ivy.array([1, 1, 1, 0])
>>> x = ivy.array([[6, 4, 2],
...                [1, 3, 0]])
>>> y = ivy.zeros((2,3))
>>> ivy.cummin(x, axis=0, reverse=True, out=y)
>>> print(y)
ivy.array([[1., 3., 0.],
       [1., 3., 0.]])

>>> x = ivy.array([[2, 4, 5],
...                [3, 6, 5],
...                [1, 3, 10]])
>>> ivy.cummin(x,axis=1,reverse=True, dtype='int64', out=x)
>>> print(x)
ivy.array([[ 2,  4,  5],
       [ 3,  5,  5],
       [ 1,  3, 10]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([[1, 3, 5]]),
...                   b=ivy.array([[3, 5, 7]]))
>>> y = ivy.cummin(x, axis= 0)
>>> print(y)
{
    a: ivy.array([[1, 3, 5]]),
    b: ivy.array([[3, 5, 7]])
}

>>> x = ivy.Container(a=ivy.array([[1, 3, 4]]),
...                   b=ivy.array([[3, 5, 8],
...                                [5, 6, 5]]),
...                   c=ivy.array([[2, 4, 1],
...                                [3, 6, 9],
...                                [0, 2, 3]]))
>>> y = ivy.Container(a = ivy.zeros((1, 3)),
...                   b = ivy.zeros((2, 3)),
...                   c = ivy.zeros((3,3)))
>>> ivy.cummin(x,axis=1,reverse=True, out=y)
>>> print(y)
{
    a: ivy.array([[1., 3., 4.]]),
    b: ivy.array([[3., 5., 8.],
                  [5., 5., 5.]]),
    c: ivy.array([[1., 1., 1.],
                  [3., 6., 9.],
                  [0., 2., 3.]])
}

>>> x = ivy.Container(a=ivy.array([[0],[5]]),
...                   b=ivy.array([[6, 8, 7],
...                                [4, 2, 3]]),
...                   c=ivy.array([[1, 2],
...                                [3, 4],
...                                [6, 4]]))
>>> ivy.cummin(x,axis=0,out=x)
>>> print(x)
{
    a: ivy.array([[0],
                  [0]]),
    b: ivy.array([[6, 8, 7],
                  [4, 2, 3]]),
    c: ivy.array([[1, 2],
                  [1, 2],
                  [1, 2]])
}

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

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

Compute the regularized lower gamma function of a and x.

Parameters:

self – Input array.
x (Optional[Union[Array, NativeArray]], default: None) – An additional input array. x has the same type as a.
out (Optional[Union[Array, NativeArray]], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – The lower incomplete gamma function of the array elements.

Examples

>>> a = ivy.array([2.5])
>>> x = ivy.array([1.7, 1.2])
>>> a.igamma(x)
    ivy.array([0.3614, 0.2085])

ivy.median(input, /, *, axis=None, keepdims=False, out=None)[source]#

Compute the median along the specified axis.

Parameters:

input (Array) – Input array.
axis (Optional[Union[int, Tuple[int]]], default: None) – Axis or axes along which the medians are computed. The default is to compute the median along a flattened version of the array.
keepdims (bool, default: False) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one.
out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – The median of the array elements.

Examples

>>> a = ivy.array([[10, 7, 4], [3, 2, 1]])
>>> ivy.median(a)
3.5
>>> ivy.median(a, axis=0)
ivy.array([6.5, 4.5, 2.5])

ivy.nanmean(a, /, *, axis=None, keepdims=False, dtype=None, out=None)[source]#

Compute the mean of all non-NaN elements along the specified dimensions.

Parameters:

a (Array) – Input array.
axis (Optional[Union[int, Tuple[int]]], default: None) – Axis or axes along which the means are computed. The default is to compute the mean of the flattened array.
keepdims (bool, default: False) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original a. If the value is anything but the default, then keepdims will be passed through to the mean or sum methods of sub-classes of ndarray. If the sub-classes methods does not implement keepdims any exceptions will be raised.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – The desired data type of returned tensor. Default is None.
out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – The nanmean of the array elements.

Examples

>>> a = ivy.array([[1, ivy.nan], [3, 4]])
>>> ivy.nanmean(a)
2.6666666666666665
>>> ivy.nanmean(a, axis=0)
ivy.array([2.,  4.])

ivy.nanmedian(input, /, *, axis=None, keepdims=False, overwrite_input=False, out=None)[source]#

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

Parameters:

self – Input array.
axis (Optional[Union[int, Tuple[int]]], default: None) – Axis or axes along which the means are computed. The default is to compute the mean of the flattened array.
keepdims (bool, default: False) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original a. If the value is anything but the default, then keepdims will be passed through to the mean or sum methods of sub-classes of ndarray. If the sub-classes methods does not implement keepdims any exceptions will be raised.
overwrite_input (bool, default: False) – If True, then allow use of memory of input array a for calculations. The input array will be modified by the call to median. This will save memory when you do not need to preserve the contents of the input array. Treat the input as undefined, but it will probably be fully or partially sorted. Default is False. If overwrite_input is True and a is not already an ndarray, an error will be raised.
out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – A new array holding the result. If the input contains integers
This function is *nestable*, and therefore also accepts (code:’ivy.Container’)
instance in place of the argument.

Examples

With ivy.Array input:

>>> x = ivy.array([[12.0, 10.0, 34.0], [45.0, 23.0, ivy.nan]])
>>> ivy.nanmedian(x)
    ivy.array(23.)
With a mix of :class:`ivy.Container` and :class:`ivy.Array` input:
>>> x = ivy.Container(a=ivy.array([[10.0, ivy.nan, 4], [3, 2, 1]]),
        b=ivy.array([[12, 10, 34], [45, 23, ivy.nan]]))
>>> ivy.nanmedian(x)
{
    a: ivy.array(3.),
    b: ivy.array(23.)
}

ivy.nanmin(x, /, *, axis=None, keepdims=False, out=None, initial=None, where=None)[source]#

Return minimum of an array or minimum along an axis, ignoring any NaNs.

Parameters:

a – Input array.
axis (Optional[Union[int, Tuple[int]]], default: None) – Axis or axes along which the minimum is computed. The default is to compute the minimum of the flattened array.
out (Optional[Array], default: None) – optional output array, for writing the result to.
keepdims (Optional[bool], default: False) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original a.
initial (Optional[Union[int, float, complex]], default: None) – The maximum value of an output element.
where (Optional[Array], default: None) – Elements to compare for the minimum

Return type:

Array

Returns:

ret – Return minimum of an array or minimum along an axis, ignoring any NaNs

Functional Examples

>>> a = ivy.array([[1, ivy.nan], [3, 4]])
>>> ivy.nanmin(a)
1.0
>>> ivy.nanmin(a, axis=1)
[1. 3.]
>>> ivy.nanmin(a, axis=0, keepdims=True)
[[1. 2.]]

ivy.nanprod(a, /, *, axis=None, keepdims=False, dtype=None, out=None, initial=None, where=None)[source]#

Compute the product of array elements over a given axis treating Not a Numbers (NaNs) as ones.

Parameters:

a (Array) – Input array.
axis (Optional[Union[int, Tuple[int]]], default: None) – Axis or axes along which the product is computed. The default is to compute the product of the flattened array.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – The desired data type of returned array. Default is None.
out (Optional[Array], default: None) – optional output array, for writing the result to.
keepdims (Optional[bool], default: False) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original a.
initial (Optional[Union[int, float, complex]], default: None) – The starting value for this product.
where (Optional[Array], default: None) – Elements to include in the product

Return type:

Array

Returns:

ret – The product of array elements over a given axis treating Not a Numbers (NaNs) as ones

Functional Examples

>>> a = ivy.array([[1, ivy.nan], [3, 4]])
>>> ivy.nanprod(a)
12.0
>>> ivy.nanprod(a, axis=0)
[3. 4.]
>>> ivy.nanprod(a, axis=0, keepdims=True)
[[3. 4.]]

ivy.quantile(a, q, /, *, axis=None, keepdims=False, interpolation='linear', out=None)[source]#

Compute the q-th quantile of the data along the specified axis.

Parameters:

a (Array) – Input array.
q (Union[Array, float]) – Quantile or sequence of quantiles to compute, which must be between 0 and 1 inclusive.
axis (Optional[Union[int, Sequence[int]]], default: None) – Axis or axes along which the quantiles are computed. The default is to compute the quantile(s) along a flattened version of the array.
keepdims (bool, default: False) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array a.
interpolation (str, default: 'linear') – {‘nearest’, ‘linear’, ‘lower’, ‘higher’, ‘midpoint’, ‘nearest_jax’}. Default value: ‘linear’. This specifies the interpolation method to use when the desired quantile lies between two data points i < j: - linear: i + (j - i) * fraction, where fraction is the fractional part of the index surrounded by i and j. - lower: i. - higher: j. - nearest: i or j, whichever is nearest. - midpoint: (i + j) / 2. linear and midpoint interpolation do not work with integer dtypes. - nearest_jax: provides jax-like computation for interpolation=’nearest’.
out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – A (rank(q) + N - len(axis)) dimensional array of same dtype as a, or, if axis is None, a rank(q) array. The first rank(q) dimensions index quantiles for different values of q.

Examples

>>> a = ivy.array([[10., 7., 4.], [3., 2., 1.]])
>>> q = ivy.array(0.5)
>>> ivy.quantile(a, q)
ivy.array(3.5)

>>> a = ivy.array([[10., 7., 4.], [3., 2., 1.]])
>>> q = 0.5
>>> ivy.quantile(a, q)
ivy.array(3.5)

>>> ivy.quantile(a, q, axis=0)
ivy.array([6.5, 4.5, 2.5])

>>> ivy.quantile(a, q, axis=1)
ivy.array([7.,  2.])

>>> ivy.quantile(a, q, axis=1, keepdims=True)
ivy.array([[7.],[2.]])

>>> a = ivy.array([1., 2., 3., 4.])
>>> q = ivy.array([0.3, 0.7])
>>> ivy.quantile(a, q, interpolation='lower')
ivy.array([1., 3.])