Ctrl+K

mean#

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

Calculate the arithmetic mean of the input array x.

Special Cases

Let N equal the number of elements over which to compute the arithmetic mean. - If N is 0, the arithmetic mean is NaN. - If x_i is NaN, the arithmetic mean is NaN (i.e., NaN values

propagate).

Parameters:

  • x (Union[Array, NativeArray]) – input array. Should have a floating-point data type.

  • axis (Optional[Union[int, Sequence[int]]], default: None) – axis or axes along which arithmetic means must be computed. By default, the mean must be computed over the entire array. If a Sequence of integers, arithmetic means must be computed over multiple axes. Default: None.

  • keepdims (bool, default: False) – bool, if True, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see broadcasting). Otherwise, if False, the reduced axes (dimensions) must not be included in the result. Default: False.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – the desired data type of returned tensor. If specified, the input tensor is casted to dtype before the operation is performed. This is useful for preventing data type overflows. Default: None.

  • out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – array, if the arithmetic mean was computed over the entire array, a zero-dimensional array containing the arithmetic mean; otherwise, a non-zero-dimensional array containing the arithmetic means. The returned array must have the same data type as x. .. note:

While this specification recommends that this function only accept input
arrays having a floating-point data type, specification-compliant array
libraries may choose to accept input arrays having an integer data type.
While mixed data type promotion is implementation-defined, if the input
array ``x`` has an integer data type, the returned array must have the
default floating-point data type.

This function conforms to the Array API Standard. This docstring is an extension of the docstring 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([3., 4., 5.])
>>> y = ivy.mean(x)
>>> print(y)
ivy.array(4.)

>>> x = ivy.array([0., 1., 2.])
>>> y = ivy.array(0.)
>>> ivy.mean(x, out=y)
>>> print(y)
ivy.array(1.)

>>> x = ivy.array([[-1., -2., -3., 0., -1.], [1., 2., 3., 0., 1.]])
>>> y = ivy.array([0., 0.])
>>> ivy.mean(x, axis=1, out=y)
>>> print(y)
ivy.array([-1.4,  1.4])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([-1., 0., 1.]), b=ivy.array([1.1, 0.2, 1.4]))
>>> y = ivy.mean(x)
>>> print(y)
{
    a: ivy.array(0.),
    b: ivy.array(0.90000004)
}

>>> x = ivy.Container(a=ivy.array([[0., 1., 2.], [3., 4., 5.]]),
...                   b=ivy.array([[3., 4., 5.], [6., 7., 8.]]))
>>> y = ivy.Container(a = ivy.zeros(3), b = ivy.zeros(3))
>>> ivy.mean(x, axis=0, out=y)
>>> print(y)
{
    a: ivy.array([1.5, 2.5, 3.5]),
    b: ivy.array([4.5, 5.5, 6.5])
}
Array.mean(self, /, axis=None, keepdims=False, *, dtype=None, out=None)[source]#

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

Special Cases

Let N equal the number of elements over which to compute the arithmetic mean. - If N is 0, the arithmetic mean is NaN. - If x_i is NaN, the arithmetic mean is NaN (i.e., NaN

values propagate).

Parameters:

  • self (Array) – input array. Should have a floating-point data type.

  • axis (Optional[Union[int, Sequence[int]]], default: None) – axis or axes along which arithmetic means must be computed. By default, the mean must be computed over the entire array. If a Sequence of integers, arithmetic means must be computed over multiple axes. Default: None.

  • keepdims (bool, default: False) – bool, if True, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see broadcasting). Otherwise, if False, the reduced axes (dimensions) must not be included in the result. Default: False.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – the desired data type of returned tensor. If specified, the input tensor is casted to dtype before the operation is performed. This is useful for preventing data type overflows. Default: None.

  • out (Optional[Array], default: None) – optional output array, for writing the result to.

Return type:

Array

Returns:

ret – array, if the arithmetic mean was computed over the entire array, a zero-dimensional array containing the arithmetic mean; otherwise, a non-zero-dimensional array containing the arithmetic means. The returned array must have the same data type as x.

Examples

With ivy.Array input:

>>> x = ivy.array([3., 4., 5.])
>>> y = x.mean()
>>> print(y)
ivy.array(4.)

>>> x = ivy.array([-1., 0., 1.])
>>> y = ivy.mean(x)
>>> print(y)
ivy.array(0.)

>>> x = ivy.array([0.1, 1.1, 2.1])
>>> y = ivy.array(0.)
>>> x.mean(out=y)
>>> print(y)
ivy.array(1.1)

>>> x = ivy.array([1., 2., 3., 0., -1.])
>>> y = ivy.array(0.)
>>> ivy.mean(x, out=y)
>>> print(y)
ivy.array(1.)

>>> x = ivy.array([[-0.5, 1., 2.], [0.0, 1.1, 2.2]])
>>> y = ivy.zeros((1, 3))
>>> x.mean(axis=0, keepdims=True, out=y)
>>> print(y)
ivy.array([[-0.25      ,  1.04999995,  2.0999999 ]])

>>> x = ivy.array([[0., 1., 2.], [3., 4., 5.]])
>>> y = ivy.array([0., 0.])
>>> ivy.mean(x, axis=1, out=y)
>>> print(y)
ivy.array([1., 4.])
Container.mean(self, /, axis=None, keepdims=False, *, dtype=None, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

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

Parameters:

  • self (Container) – input container. Should have a floating-point data type.

  • axis (Optional[Union[int, Sequence[int], Container]], default: None) – axis or axes along which arithmetic means must be computed. By default, the mean must be computed over the entire array. If a Sequence of integers, arithmetic means must be computed over multiple axes. Default: None.

  • keepdims (Union[bool, Container], default: False) – bool, if True, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see broadcasting). Otherwise, if False, the reduced axes (dimensions) must not be included in the result. Default: False.

  • dtype (Optional[Union[Dtype, NativeDtype]], default: None) – the desired data type of returned tensor. If specified, the input tensor is casted to dtype before the operation is performed. This is useful for preventing data type overflows. Default: None.

  • 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 – container, if the arithmetic mean was computed over the entire array, a zero-dimensional array containing the arithmetic mean; otherwise, a non-zero-dimensional array containing the arithmetic means. The returned array must have the same data type as self.

Examples

With ivy.Container input:

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

>>> x = ivy.Container(a=ivy.array([0.1, 1.1]), b=ivy.array([0.1, 1.1, 2.1]))
>>> y = x.mean(keepdims=True)
>>> print(y)
{
    a: ivy.array([0.60000002]),
    b: ivy.array([1.10000002])
}

>>> x = ivy.Container(a=ivy.array([[0.1, 1.1]]), b=ivy.array([[2., 4.]]))
>>> y = x.mean(axis=1, keepdims=True)
>>> print(y)
{
    a: ivy.array([[0.60000002]]),
    b: ivy.array([[3.]])
}

>>> x = ivy.Container(a=ivy.array([-1., 0., 1.]), b=ivy.array([1.1, 0.2, 1.4]))
>>> x.mean(out=x)
>>> print(x)
{
    a: ivy.array(0.),
    b: ivy.array(0.9)
}

>>> x = ivy.Container(a=ivy.array([0., -1., 1.]), b=ivy.array([1., 1., 1.]))
>>> y = ivy.Container(a=ivy.array(0.), b=ivy.array(0.))
>>> x.mean(out=y)
>>> print(y)
{
    a: ivy.array(0.),
    b: ivy.array(1.)
}

>>> x = ivy.Container(a=ivy.array([[0., 1., 2.], [3., 4., 5.]]),
...                   b=ivy.array([[3., 4., 5.], [6., 7., 8.]]))
>>> x.mean(axis=0, out=x)
>>> print(x)
{
    a: ivy.array([1.5, 2.5, 3.5]),
    b: ivy.array([4.5, 5.5, 6.5])
}

>>> x = ivy.Container(a=ivy.array([[1., 1., 1.], [2., 2., 2.]]),
...                   b=ivy.array([[3., 3., 3.], [4., 4., 4.]]))
>>> y = ivy.mean(x, axis=1)
>>> print(y)
{
    a: ivy.array([1., 2.]),
    b: ivy.array([3., 4.])
}
On this page