# xsort¶

Defined in `xtensor/xsort.hpp`

group xt_xsort

Because sorting functions need to access the tensor data repeatedly, they evaluate their input and may allocate temporaries.

Enums

enum quantile_method

Quantile interpolation method.

Predefined methods for interpolating quantiles, as defined in (Hyndman and Fan, 1996).

(Hyndman and Fan, 1996) R. J. Hyndman and Y. Fan, “Sample quantiles in statistical packages”, The American Statistician, 50(4), pp. 361-365, 1996

Values:

enumerator interpolated_inverted_cdf

Method 4 of (Hyndman and Fan, 1996) with `alpha=0` and `beta=1`.

enumerator hazen

Method 5 of (Hyndman and Fan, 1996) with `alpha=1/2` and `beta=1/2`.

enumerator weibull

Method 6 of (Hyndman and Fan, 1996) with `alpha=0` and `beta=0`.

enumerator linear

Method 7 of (Hyndman and Fan, 1996) with `alpha=1` and `beta=1`.

enumerator median_unbiased

Method 8 of (Hyndman and Fan, 1996) with `alpha=1/3` and `beta=1/3`.

enumerator normal_unbiased

Method 9 of (Hyndman and Fan, 1996) with `alpha=3/8` and `beta=3/8`.

Functions

template<class E>
inline auto sort(const xexpression<E> &e, std::ptrdiff_t axis = -1)

Sort xexpression (optionally along axis) The sort is performed using the `std::sort` functions.

A copy of the xexpression is created and returned.

Parameters
• e – xexpression to sort

• axis – axis along which sort is performed

Returns

sorted array (copy)

template<class E>
inline auto argsort(const xexpression<E> &e, std::ptrdiff_t axis = -1)

Argsort xexpression (optionally along axis) Performs an indirect sort along the given axis.

Returns an xarray of indices of the same shape as e that index data along the given axis in sorted order.

Parameters
• e – xexpression to argsort

• axis – axis along which argsort is performed

Returns

argsorted index array

template<class E, class C, class R = detail::flatten_sort_result_type_t<E>, class = std::enable_if_t<!xtl::is_integral<C>::value, int>>
inline R partition(const xexpression<E> &e, const C &kth_container, placeholders::xtuph)

Partially sort xexpression.

Partition shuffles the xexpression in a way so that the kth element in the returned xexpression is in the place it would appear in a sorted array and all elements smaller than this entry are placed (unsorted) before.

The optional third parameter can either be an axis or `xnone()` in which case the xexpression will be flattened.

This function uses `std::nth_element` internally.

```xt::xarray<float> a = {1, 10, -10, 123};
std::cout << xt::partition(a, 0) << std::endl; // {-10, 1, 123, 10} the correct entry at index 0
std::cout << xt::partition(a, 3) << std::endl; // {1, 10, -10, 123} the correct entry at index 3
std::cout << xt::partition(a, {0, 3}) << std::endl; // {-10, 1, 10, 123} the correct entries at index 0
and 3
```

Parameters
• e – input xexpression

• kth_container – a container of `indices` that should contain the correctly sorted value

• axis – either integer (default = -1) to sort along last axis or `xnone()` to flatten before sorting

Returns

partially sorted xcontainer

template<class E, class C, class R = typename detail::linear_argsort_result_type<typename detail::sort_eval_type<E>::type>::type, class = std::enable_if_t<!xtl::is_integral<C>::value, int>>
inline R argpartition(const xexpression<E> &e, const C &kth_container, placeholders::xtuph)

Partially sort arguments.

Argpartition shuffles the indices to a xexpression in a way so that the index for the kth element in the returned xexpression is in the place it would appear in a sorted array and all elements smaller than this entry are placed (unsorted) before.

The optional third parameter can either be an axis or `xnone()` in which case the xexpression will be flattened.

This function uses `std::nth_element` internally.

```xt::xarray<float> a = {1, 10, -10, 123};
std::cout << xt::argpartition(a, 0) << std::endl; // {2, 0, 3, 1} the correct entry at index 0
std::cout << xt::argpartition(a, 3) << std::endl; // {0, 1, 2, 3} the correct entry at index 3
std::cout << xt::argpartition(a, {0, 3}) << std::endl; // {2, 0, 1, 3} the correct entries at index 0
and 3
```

Parameters
• e – input xexpression

• kth_container – a container of `indices` that should contain the correctly sorted value

• axis – either integer (default = -1) to sort along last axis or `xnone()` to flatten before sorting

Returns

xcontainer with indices of partial sort of input

template<class T = double, class E, class P>
inline auto quantile(E &&e, const P &probas, std::ptrdiff_t axis, T alpha, T beta)

Compute quantiles over the given axis.

In a sorted array represneting a distribution of numbers, the quantile of a probability `p` is the the cut value `q` such that a fraction `p` of the distribution is lesser or equal to `q`. When the cutpoint falls between two elemnts of the sample distribution, a interpolation is computed using the `alpha` and `beta` coefficients, as descripted in (Hyndman and Fan, 1996).

The algorithm partially sorts entries in a copy along the `axis` axis.

(Hyndman and Fan, 1996) R. J. Hyndman and Y. Fan, “Sample quantiles in statistical packages”, The American Statistician, 50(4), pp. 361-365, 1996

Parameters
• e – Expression containing the distribution over which the quantiles are computed.

• probas – An list of probability associated with each desired quantiles. All elements must be in the range `[0, 1]`.

• axis – The dimension in which to compute the quantiles, i.e the axis representing the distribution.

• alpha – Interpolation parameter. Must be in the range `[0, 1]]`.

• beta – Interpolation parameter. Must be in the range `[0, 1]]`.

Template Parameters

T – The type in which the quatile are computed.

Returns

An expression with as many dimensions as the input `e`. The first axis correspond to the quantiles. The other axes are the axes that remain after the reduction of `e`.

template<class T = double, class E, class P>
inline auto quantile(E &&e, const P &probas, T alpha, T beta)

Compute quantiles of the whole expression.

The quantiles are computed over the whole expression, as if flatten in a one-dimensional expression.

template<class T = double, class E, class P>
inline auto quantile(E &&e, const P &probas, std::ptrdiff_t axis, quantile_method method = quantile_method::linear)

Compute quantiles over the given axis.

The function takes the name of a predefined method to compute to interpolate between values.

template<class T = double, class E, class P>
inline auto quantile(E &&e, const P &probas, quantile_method method = quantile_method::linear)

Compute quantiles of the whole expression.

The quantiles are computed over the whole expression, as if flatten in a one-dimensional expression. The function takes the name of a predefined method to compute to interpolate between values.

template<class E>
inline auto median(E &&e, std::ptrdiff_t axis)

Find the median along the specified axis.

Given a vector V of length N, the median of V is the middle value of a sorted copy of V, V_sorted - i e., V_sorted[(N-1)/2], when N is odd, and the average of the two middle values of V_sorted when N is even.

Parameters
• axis – axis along which the medians are computed. If not set, computes the median along a flattened version of the input.

• e – input xexpression

Returns

median value

template<layout_type L = ::xt::layout_type::row_major, class E>
inline auto argmax(const xexpression<E> &e, std::ptrdiff_t axis)

Find position of maximal value in xexpression By default, the returned index is into the flattened array.

If `axis` is specified, the indices are along the specified axis.

Parameters
• e – input xexpression

• axis – select axis (optional)

Returns

returns xarray with positions of maximal value

template<class E>
inline auto unique(const xexpression<E> &e)

Find unique elements of a xexpression.

This returns a flattened xtensor with sorted, unique elements from the original expression.

Parameters

e – input xexpression (will be flattened)

template<class E1, class E2>
inline auto setdiff1d(const xexpression<E1> &ar1, const xexpression<E2> &ar2)

Find the set difference of two xexpressions.

This returns a flattened xtensor with the sorted, unique values in ar1 that are not in ar2.

Parameters
• ar1 – input xexpression (will be flattened)

• ar2 – input xexpression