diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 29b34f560ab2e..26b71cc7b653c 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -39,6 +39,7 @@ IgnoreRaise, IndexLabel, IndexT, + NaPosition, Scalar, Self, Shape, @@ -2398,8 +2399,52 @@ def append(self, other): return Index(new_tuples) def argsort( - self, *args, na_position: str = "last", **kwargs + self, *args, na_position: NaPosition = "last", **kwargs ) -> npt.NDArray[np.intp]: + """ + Return the integer indices that would sort the index. + + Parameters + ---------- + *args + Passed to `numpy.ndarray.argsort`. + na_position : {'first' or 'last'}, default 'last' + Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at + the end. + **kwargs + Passed to `numpy.ndarray.argsort`. + + Returns + ------- + np.ndarray[np.intp] + Integer indices that would sort the index if used as + an indexer. + + See Also + -------- + numpy.argsort : Similar method for NumPy arrays. + Index.argsort : Similar method for Index. + + Examples + -------- + >>> midx = pd.MultiIndex.from_arrays([[3, 2], ["e", "c"]]) + >>> midx + MultiIndex([(3, 'e'), (2, 'c')]) + + >>> order = midx.argsort() + >>> order + array([1, 0]) + + >>> midx[order] + Index(['a', 'b', 'c', 'd'], dtype='object') + + >>> midx = pd.MultiIndex.from_arrays([[2, 2], [np.nan, 0]]) + >>> midx.argsort(na_position="first") + array([0, 1]) + + >>> midx.argsort() + array([1, 0]) + """ target = self._sort_levels_monotonic(raise_if_incomparable=True) keys = [lev.codes for lev in target._get_codes_for_sorting()] return lexsort_indexer(keys, na_position=na_position, codes_given=True)