Reducing functions

xtensor provides the following reducing functions for xexpressions:

Defined in xtensor/core/xmath.hpp and xtensor/reducers/xnorm.hpp.

group reducing functions

Functions

template<class T = void, class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<std::negation<is_reducer_options<X>>, std::negation<xtl::is_integral<std::decay_t<X>>>> = 0> inline auto 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 X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<std::negation<is_reducer_options<X>>, std::negation<xtl::is_integral<std::decay_t<X>>>> = 0> inline auto 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 X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<std::negation<is_reducer_options<X>>> = 0> inline auto 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 W, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>, std::negation<xtl::is_integral<X>>> = 0> inline auto average(E &&e, W &&weights, X &&axes, EVS ev = EVS())

Average of elements over given axes using weights.

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

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

template<class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0> inline auto minmax(E &&e, EVS es = EVS())

Minimum and maximum among the elements of an array or expression.

Returns an xreducer for the minimum and maximum of an expression’s elements.

Parameters:

e – an xexpression
es – evaluation strategy to use (lazy (default), or immediate)

Returns:

an xexpression of type std::array<value_type, 2>, whose first and second element represent the minimum and maximum respectively

template<class T> auto diff(const xexpression<T> &a, std::size_t n = 1, std::ptrdiff_t axis = -1)

Calculate the n-th discrete difference along the given axis.

Calculate the n-th discrete difference along the given axis. This function is not lazy (might change in the future).

Parameters:

a – an xexpression
n – The number of times values are differenced. If zero, the input is returned as-is. (optional)
axis – The axis along which the difference is taken, default is the last axis.

Returns:

an xarray

template<class T> auto 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 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

template<class E, class X, class EVS, class> auto 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 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 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 EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_xexpression<E>> = 0> inline auto norm_l2(E &&e, EVS es = EVS()) noexcept

L2 norm of a scalar or array-like argument.

Parameters:

e – an xexpression
es – evaluation strategy to use (lazy (default), or immediate) For scalar types: implemented as abs(t) otherwise: implemented as sqrt(norm_sq(t)).

template<class E, class X, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_xexpression<E>, std::negation<is_reducer_options<X>>> = 0> inline auto 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 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<std::negation<is_reducer_options<X>>> = 0> inline auto 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<std::negation<is_reducer_options<X>>> = 0> inline auto 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 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 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)