# xsort

Defined in `xtensor/misc/xsort.hpp`

group Sorting functions.

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

  Enums

  enum class quantile_method

    Quantile interpolation method.

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

    See also

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

    See also

    xt::quantile(E&& e, P const& probas, std::ptrdiff_t axis, xt::quantile_method method)

    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, sorting_method method = sorting_method::quick)

    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.

    See also

    xt::sorting_method

    Parameters:

      - e – xexpression to argsort

      - axis – axis along which argsort is performed

      - method – sorting algorithm to use

    Returns:

      argsorted index array

  template<class E, xtl::non_integral_concept C, class R = detail::flatten_sort_result_type_t<E>>
  inline R partition(const xexpression<E> &e, 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, xtl::non_integral_concept C, class R = typename detail::linear_argsort_result_type<typename detail::sort_eval_type<E>::type>::type>
  inline R argpartition(const xexpression<E> &e, 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.

    See also

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

    See also

    https://en.wikipedia.org/wiki/Quantile

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

    See also

    xt::quantile(E&& e, P const& probas, std::ptrdiff_t axis, T alpha, T beta)

  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.

    See also

    xt::quantile_method

    See also

    xt::quantile(E&& e, P const& probas, std::ptrdiff_t axis, T alpha, T beta)

  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.

    See also

    xt::quantile_method

    See also

    xt::quantile(E&& e, P const& probas, std::ptrdiff_t axis, xt::quantile_method method)

  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