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

.. py:module:: arkouda.numpy.sorting


Attributes
----------

.. autoapisummary::

   arkouda.numpy.sorting.SortingAlgorithm


Functions
---------

.. autoapisummary::

   arkouda.numpy.sorting.argsort
   arkouda.numpy.sorting.coargsort
   arkouda.numpy.sorting.searchsorted
   arkouda.numpy.sorting.sort


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

.. py:data:: SortingAlgorithm

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

   Return the permutation (indices) that sorts the array.

   :param pda: The array to sort (supported: int64, uint64, float64 for pdarray).
   :type pda: pdarray, Strings, or Categorical
   :param algorithm: The algorithm to use for sorting.
   :type algorithm: SortingAlgorithm, default SortingAlgorithm.RadixSortLSD
   :param axis: Axis to sort along. Negative values are normalized against the array rank.
                For 1D types (Strings, Categorical), must be 0.
   :type axis: int, default 0
   :param ascending: Sort order.
   :type ascending: bool, default True

   :returns: Indices such that ``pda[indices]`` is sorted.
   :rtype: pdarray

   :raises TypeError: If `pda` is not a pdarray, Strings, or Categorical.
   :raises ValueError: If `axis` is out of bounds.

   .. seealso:: :py: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

   >>> import arkouda as ak
   >>> a = ak.randint(0, 10, 10, seed=1)
   >>> a
   array([7 9 5 1 4 1 8 5 5 0])
   >>> perm = ak.argsort(a)
   >>> a[perm]
   array([0 1 1 4 5 5 5 7 8 9])
   >>> ak.argsort(a, ak.sorting.SortingAlgorithm["RadixSortLSD"])
   array([9 3 5 4 2 7 8 0 6 1])
   >>> ak.argsort(a, ak.sorting.SortingAlgorithm["TwoArrayRadixSort"])
   array([9 3 5 4 2 7 8 0 6 1])
   >>> ak.argsort(a, ascending=False)
   array([1 6 0 8 7 2 4 5 3 9])


.. py:function:: coargsort(arrays: Sequence[Union[arkouda.numpy.strings.Strings, arkouda.numpy.pdarrayclass.pdarray, arkouda.pandas.categorical.Categorical]], algorithm: SortingAlgorithm = SortingAlgorithm.RadixSortLSD, ascending: bool = True) -> arkouda.numpy.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 or Categoricals — those are grouped, not ordered.

   :param arrays: The columns (int64, uint64, float64, Strings, or Categorical) to sort by row.
   :type arrays: Sequence of Strings, pdarray, or Categorical
   :param algorithm: The algorithm to be used for sorting the arrays.
   :type algorithm: SortingAlgorithm, default=SortingAlgorithm.RadixSortLSD
   :param ascending: Whether to sort in ascending order. Ignored when arrays have ndim > 1.
   :type ascending: bool, default=True

   :returns: The indices that permute the rows into grouped order.
   :rtype: pdarray

   :raises ValueError: If the inputs are not all the same size or not valid array types.

   .. seealso:: :py: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.

   For Strings, sorting is based on a hash. This ensures grouping of identical strings,
   but not lexicographic order. For Categoricals, sorting is based on the internal codes.

   .. rubric:: Examples

   >>> import arkouda as ak
   >>> 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:: searchsorted(a: arkouda.numpy.pdarrayclass.pdarray, v: Union[arkouda.numpy.dtypes.int_scalars, arkouda.numpy.dtypes.float64, arkouda.numpy.dtypes.bigint, arkouda.numpy.pdarrayclass.pdarray], side: Literal['left', 'right'] = 'left', x2_sorted: bool = False) -> Union[int, arkouda.numpy.pdarrayclass.pdarray]

   Find indices where elements should be inserted to maintain order.

   Find the indices into a sorted array `a` such that, if the corresponding
   elements in `v` were inserted before the indices, the order of `a` would be preserved.

   :param a: 1-D input array. Must be sorted in ascending order. `sorter` is not currently supported.
   :type a: pdarray
   :param v: Values to insert into `a`. Can be a scalar or array-like.
   :type v: int_scalars, float64, bigint, or pdarray
   :param side: If 'left', the index of the first suitable location found is given.
                If 'right', return the last such index.
   :type side: {'left', 'right'}, default='left'
   :param x2_sorted: If True, assumes that `v` (x2) is already sorted in ascending order. This can improve performance
                     for large, sorted search arrays. If False, no assumption is made about the order of `v`.
   :type x2_sorted: bool, default=False

   :returns: **indices** -- If `v` is an array, returns an array of insertion points with the same shape.
             If `v` is a scalar, returns a single integer index.
   :rtype: int or pdarray

   :raises ValueError: If `a` has more than one dimension.
   :raises TypeError: If `a` has an unsupported dtype (i.e., not int64, uint64, bigint, or float64).
       If the dtype of `a` and `v` does not match

   .. rubric:: Examples

   >>> import arkouda as ak
   >>> a = ak.array([11, 12, 13, 14, 15])
   >>> ak.searchsorted(a, 13)
   2
   >>> ak.searchsorted(a, 13, side='right')
   3
   >>> v = ak.array([-10, 20, 12, 13])
   >>> ak.searchsorted(a, v)
   array([0 5 1 2])
   >>> v_sorted = ak.array([-10, 12, 13, 20])
   >>> ak.searchsorted(a, v_sorted, x2_sorted=True)
   array([0 1 2 5])


.. py:function:: sort(pda: arkouda.numpy.pdarrayclass.pdarray, algorithm: SortingAlgorithm = SortingAlgorithm.RadixSortLSD, axis: arkouda.numpy.dtypes.int_scalars = -1) -> arkouda.numpy.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
   :param algorithm: The algorithm to be used for sorting the arrays.
   :type algorithm: SortingAlgorithm, default=SortingAlgorithm.RadixSortLSD
   :param axis: The axis to sort over. Setting to -1 means that it will sort over axis = ndim - 1.
   :type axis: int_scalars, default=-1

   :returns: The sorted copy of pda
   :rtype: pdarray

   :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:: :py: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

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