# 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>
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>
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.

Return

an xreducer

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.

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
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>
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.

Return

an xreducer

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.

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
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>
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.

Return
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.

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
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>
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>
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.

Return
See

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.

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
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>
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.

Return
See

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.

template<class T>
auto xt::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).

Return

an xarray

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.

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
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>
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.

Return

an xreducer

Parameters
• e: an xexpression

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

• es: evaluation strategy of the reducer

template<class T = void, class E, class EVS = std::tuple<evaluation_strategy::lazy_type>, xtl::check_concept<is_reducer_options<EVS>> = 0>
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>
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.

Return

an xreducer

Parameters
• e: an xexpression

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

• es: evaluation strategy of the reducer

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).

Return

an xarray

Parameters
• y: an xexpression

• dx: the spacing between sample points (optional)

• axis: the axis along which to integrate.

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).

Return

an xarray

Parameters
• y: an xexpression

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

• axis: the axis along which to integrate.

Defined in xtensor/xnorm.hpp

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

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.

Return

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.

Parameters
• e: an xexpression

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

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

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

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

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

Return

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.

Parameters
• e: an xexpression

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

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

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

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.

Return

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.

Parameters
• e: an xexpression

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

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

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>
auto xt::norm_l2(E &&e, X &&axes, EVS es = EVS())

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

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

Return

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

Parameters
• e: an xexpression

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

• axes: the axes along which the norm is computed

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

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

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

Return

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.

Parameters
• e: an xexpression

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

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

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

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.

Return

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.

Parameters
• e: an xexpression

• p:

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

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

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

Return

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.

Parameters
• e: an xexpression

• p:

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

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

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

Return

an xreducer (or xcontainer, depending on evaluation strategy)

Parameters
• e: a 2D xexpression

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

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

Return

an xreducer (or xcontainer, depending on evaluation strategy)

Parameters
• e: a 2D xexpression

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