Reducing functions

xtensor provides the following reducing functions for xexpressions:

Defined in xtensor/xmath.hpp

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::sum(E &&e, EVS es = EVS())
template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>, xtl::negation<xtl::is_integral<std::decay_t<X>>>> = 0>
inline auto xt::sum(E &&e, X &&axes, EVS es = EVS())

Sum of elements over given axes.

Returns an xreducer for the sum of elements over given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the sum is performed (optional)

  • es – evaluation strategy of the reducer

Template Parameters:

T – the value type used for internal computation. The default is E::value_type. T is also used for determining the value type of the result, which is the type of T() + E::value_type(). You can pass big_promote_value_type_t<E> to avoid overflow in computation.

Returns:

an xreducer

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::prod(E &&e, EVS es = EVS())
template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>, xtl::negation<xtl::is_integral<std::decay_t<X>>>> = 0>
inline auto xt::prod(E &&e, X &&axes, EVS es = EVS())

Product of elements over given axes.

Returns an xreducer for the product of elements over given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the product is computed (optional)

  • ddof – delta degrees of freedom (optional). The divisor used in calculations is N - ddof, where N represents the number of elements. By default ddof is zero.

  • es – evaluation strategy of the reducer

Template Parameters:

T – the value type used for internal computation. The default is E::value_type. T is also used for determining the value type of the result, which is the type of T() * E::value_type(). You can pass big_promote_value_type_t<E> to avoid overflow in computation.

Returns:

an xreducer

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::mean(E &&e, EVS es = EVS())
template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>> = 0>
inline auto xt::mean(E &&e, X &&axes, EVS es = EVS())

Mean of elements over given axes.

Returns an xreducer for the mean of elements over given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the mean is computed (optional)

  • es – the evaluation strategy (optional)

Template Parameters:

T – the value type used for internal computation. The default is E::value_type. T is also used for determining the value type of the result, which is the type of T() + E::value_type(). You can pass big_promote_value_type_t<E> to avoid overflow in computation.

Returns:

an xexpression

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::average(E &&e, EVS ev = EVS())
template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::variance(E &&e, EVS es = EVS())
template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>, xtl::negation<xtl::is_integral<std::decay_t<X>>>, is_reducer_options<EVS>> = 0>
inline auto xt::variance(E &&e, X &&axes, EVS es = EVS())
template<class T = void, class E, class X, class D, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>, xtl::is_integral<D>> = 0>
inline auto xt::variance(E &&e, X &&axes, const D &ddof, EVS es = EVS())

Compute the variance along the specified axes.

Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axes.

Note: this function is not yet specialized for complex numbers.

See also

stddev, mean

Parameters:
  • e – an xexpression

  • axes – the axes along which the variance is computed (optional)

  • ddof – delta degrees of freedom (optional). The divisor used in calculations is N - ddof, where N represents the number of elements. By default ddof is zero.

  • es – evaluation strategy to use (lazy (default), or immediate)

Template Parameters:

T – the value type used for internal computation. The default is E::value_type. Tis also used for determining the value type of the result, which is the type of T() + E::value_type(). You can pass big_promote_value_type_t<E> to avoid overflow in computation.

Returns:

an xexpression

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::stddev(E &&e, EVS es = EVS())
template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>> = 0>
inline auto xt::stddev(E &&e, X &&axes, EVS es = EVS())

Compute the standard deviation along the specified axis.

Returns the standard deviation, a measure of the spread of a distribution, of the array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis.

Note: this function is not yet specialized for complex numbers.

See also

variance, mean

Parameters:
  • e – an xexpression

  • axes – the axes along which the standard deviation is computed (optional)

  • es – evaluation strategy to use (lazy (default), or immediate)

Template Parameters:

T – the value type used for internal computation. The default is E::value_type. Tis also used for determining the value type of the result, which is the type of T() + E::value_type(). You can pass big_promote_value_type_t<E> to avoid overflow in computation.

Returns:

an xexpression

Warning

doxygenfunction: Unable to resolve function “diff” with arguments (const xexpression<T>&, unsigned int, std::ptrdiff_t) in doxygen xml output for project “xtensor” from directory: ../xml. Potential matches:

- template<class T> auto diff(const xexpression<T> &a, std::size_t n = 1, std::ptrdiff_t axis = -1)
template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::amax(E &&e, EVS es = EVS())
template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>, xtl::negation<xtl::is_integral<std::decay_t<X>>>> = 0>
inline auto xt::amax(E &&e, X &&axes, EVS es = EVS())

Maximum element along given axis.

Returns an xreducer for the maximum of elements over given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the maximum is found (optional)

  • es – evaluation strategy of the reducer

Returns:

an xreducer

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
inline auto xt::amin(E &&e, EVS es = EVS())
template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>, xtl::negation<xtl::is_integral<std::decay_t<X>>>> = 0>
inline auto xt::amin(E &&e, X &&axes, EVS es = EVS())

Minimum element along given axis.

Returns an xreducer for the minimum of elements over given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the minimum is found (optional)

  • es – evaluation strategy of the reducer

Returns:

an xreducer

template<class T>
auto xt::trapz(const xexpression<T> &y, double dx = 1.0, std::ptrdiff_t axis = -1)

Integrate along the given axis using the composite trapezoidal rule.

Returns definite integral as approximated by trapezoidal rule. This function is not lazy (might change in the future).

Parameters:
  • y – an xexpression

  • dx – the spacing between sample points (optional)

  • axis – the axis along which to integrate.

Returns:

an xarray

template<class T, class E>
auto xt::trapz(const xexpression<T> &y, const xexpression<E> &x, std::ptrdiff_t axis = -1)

Integrate along the given axis using the composite trapezoidal rule.

Returns definite integral as approximated by trapezoidal rule. This function is not lazy (might change in the future).

Parameters:
  • y – an xexpression

  • x – an xexpression representing the sample points corresponding to the y values.

  • axis – the axis along which to integrate.

Returns:

an xarray

Defined in xtensor/xnorm.hpp

template<class E, class X, class EVS, class>
auto xt::norm_l0(E &&e, X &&axes, EVS es) noexcept

L0 (count) pseudo-norm of an array-like argument over given axes.

Returns an xreducer for the L0 pseudo-norm of the elements across given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the norm is computed (optional)

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy) When no axes are provided, the norm is calculated over the entire array. In this case, the reducer represents a scalar result, otherwise an array of appropriate dimension.

template<class E, class X, class EVS, class>
auto xt::norm_l1(E &&e, X &&axes, EVS es) noexcept

L1 norm of an array-like argument over given axes.

Returns an xreducer for the L1 norm of the elements across given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the norm is computed (optional)

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy) When no axes are provided, the norm is calculated over the entire array. In this case, the reducer represents a scalar result, otherwise an array of appropriate dimension.

template<class E, class X, class EVS, class>
auto xt::norm_sq(E &&e, X &&axes, EVS es) noexcept

Squared L2 norm of an array-like argument over given axes.

Returns an xreducer for the squared L2 norm of the elements across given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the norm is computed (optional)

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy) When no axes are provided, the norm is calculated over the entire array. In this case, the reducer represents a scalar result, otherwise an array of appropriate dimension.

template<class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_xexpression<E>, xtl::negation<is_reducer_options<X>>> = 0>
inline auto xt::norm_l2(E &&e, X &&axes, EVS es = EVS()) noexcept

L2 norm of an array-like argument over given axes.

Returns an xreducer for the L2 norm of the elements across given axes.

Parameters:
  • e – an xexpression

  • es – evaluation strategy to use (lazy (default), or immediate)

  • axes – the axes along which the norm is computed

Returns:

an xreducer (specifically: sqrt(norm_sq(e, axes))) (or xcontainer, depending on evaluation strategy)

template<class E, class X, class EVS, class>
auto xt::norm_linf(E &&e, X &&axes, EVS es) noexcept

Infinity (maximum) norm of an array-like argument over given axes.

Returns an xreducer for the infinity norm of the elements across given axes.

Parameters:
  • e – an xexpression

  • axes – the axes along which the norm is computed (optional)

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy) When no axes are provided, the norm is calculated over the entire array. In this case, the reducer represents a scalar result, otherwise an array of appropriate dimension.

template<class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>> = 0>
inline auto xt::norm_lp_to_p(E &&e, double p, X &&axes, EVS es = EVS()) noexcept

p-th power of the Lp norm of an array-like argument over given axes.

Returns an xreducer for the p-th power of the Lp norm of the elements across given axes.

Parameters:
  • e – an xexpression

  • p

  • axes – the axes along which the norm is computed (optional)

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy) When no axes are provided, the norm is calculated over the entire array. In this case, the reducer represents a scalar result, otherwise an array of appropriate dimension.

template<class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<xtl::negation<is_reducer_options<X>>> = 0>
inline auto xt::norm_lp(E &&e, double p, X &&axes, EVS es = EVS())

Lp norm of an array-like argument over given axes.

Returns an xreducer for the Lp norm (p != 0) of the elements across given axes.

Parameters:
  • e – an xexpression

  • p

  • axes – the axes along which the norm is computed (optional)

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy) When no axes are provided, the norm is calculated over the entire array. In this case, the reducer represents a scalar result, otherwise an array of appropriate dimension.

template<class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_xexpression<E>> = 0>
inline auto xt::norm_induced_l1(E &&e, EVS es = EVS())

Induced L1 norm of a matrix.

Returns an xreducer for the induced L1 norm (i.e. the maximum of the L1 norms of e’s columns).

Parameters:
  • e – a 2D xexpression

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy)

template<class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_xexpression<E>> = 0>
inline auto xt::norm_induced_linf(E &&e, EVS es = EVS())

Induced L-infinity norm of a matrix.

Returns an xreducer for the induced L-infinity norm (i.e. the maximum of the L1 norms of e’s rows).

Parameters:
  • e – a 2D xexpression

  • es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xreducer (or xcontainer, depending on evaluation strategy)