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)