arkouda.sorting
===============

.. py:module:: arkouda.sorting


Functions
---------

.. autoapisummary::

   arkouda.sorting.argsort
   arkouda.sorting.coargsort
   arkouda.sorting.sort


Module Contents
---------------

.. py:function:: argsort(pda: Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical], algorithm: SortingAlgorithm = SortingAlgorithm.RadixSortLSD, axis: arkouda.numpy.dtypes.int_scalars = 0) -> arkouda.pdarrayclass.pdarray

   Return the permutation that sorts the array.

   :param pda: The array to sort (int64, uint64, or float64)
   :type pda: pdarray or Strings or Categorical

   :returns: The indices such that ``pda[indices]`` is sorted
   :rtype: pdarray, int64

   :raises TypeError: Raised if the parameter is other than a pdarray or Strings

   .. seealso:: :obj:`coargsort`

   .. rubric:: Notes

   Uses a least-significant-digit radix sort, which is stable and
   resilient to non-uniformity in data but communication intensive.

   .. rubric:: Examples

   >>> a = ak.randint(0, 10, 10)
   >>> perm = ak.argsort(a)
   >>> a[perm]
   array([0, 1, 1, 3, 4, 5, 7, 8, 8, 9])


.. py:function:: coargsort(arrays: Sequence[Union[arkouda.strings.Strings, arkouda.pdarrayclass.pdarray, arkouda.categorical.Categorical]], algorithm: SortingAlgorithm = SortingAlgorithm.RadixSortLSD) -> arkouda.pdarrayclass.pdarray

   Return the permutation that groups the rows (left-to-right), if the
   input arrays are treated as columns. The permutation sorts numeric
   columns, but not strings/Categoricals -- strings/Categoricals are grouped, but not ordered.

   :param arrays: The columns (int64, uint64, float64, Strings, or Categorical) to sort by row
   :type arrays: Sequence[Union[Strings, pdarray, Categorical]]

   :returns: The indices that permute the rows to grouped order
   :rtype: pdarray, int64

   :raises ValueError: Raised if the pdarrays are not of the same size or if the parameter
       is not an Iterable containing pdarrays, Strings, or Categoricals

   .. seealso:: :obj:`argsort`

   .. rubric:: Notes

   Uses a least-significant-digit radix sort, which is stable and resilient
   to non-uniformity in data but communication intensive. Starts with the
   last array and moves forward. This sort operates directly on numeric types,
   but for Strings, it operates on a hash. Thus, while grouping of equivalent
   strings is guaranteed, lexicographic ordering of the groups is not. For Categoricals,
   coargsort sorts based on Categorical.codes which guarantees grouping of equivalent categories
   but not lexicographic ordering of those groups.

   .. rubric:: Examples

   >>> a = ak.array([0, 1, 0, 1])
   >>> b = ak.array([1, 1, 0, 0])
   >>> perm = ak.coargsort([a, b])
   >>> perm
   array([2, 0, 3, 1])
   >>> a[perm]
   array([0, 0, 1, 1])
   >>> b[perm]
   array([0, 1, 0, 1])


.. py:function:: sort(pda: arkouda.pdarrayclass.pdarray, algorithm: SortingAlgorithm = SortingAlgorithm.RadixSortLSD, axis=-1) -> arkouda.pdarrayclass.pdarray

   Return a sorted copy of the array. Only sorts numeric arrays;
   for Strings, use argsort.

   :param pda: The array to sort (int64, uint64, or float64)
   :type pda: pdarray or Categorical

   :returns: The sorted copy of pda
   :rtype: pdarray, int64, uint64, or float64

   :raises TypeError: Raised if the parameter is not a pdarray
   :raises ValueError: Raised if sort attempted on a pdarray with an unsupported dtype
       such as bool

   .. seealso:: :obj:`argsort`

   .. rubric:: Notes

   Uses a least-significant-digit radix sort, which is stable and resilient
   to non-uniformity in data but communication intensive.

   .. rubric:: Examples

   >>> a = ak.randint(0, 10, 10)
   >>> sorted = ak.sort(a)
   >>> a
   array([0, 1, 1, 3, 4, 5, 7, 8, 8, 9])