From 76eb6b214fc0c9b5a35a8a7fa659b5a86630a8c2 Mon Sep 17 00:00:00 2001 From: Gesa Stupperich Date: Sun, 20 Jun 2021 16:47:04 +0100 Subject: [PATCH 1/2] DOC: Share swaplevel docstring between Series and DataFrame (#42120) --- pandas/core/frame.py | 31 ++++++++----------- pandas/core/series.py | 70 ++++++++++++++++++++++++++++++++++++++----- 2 files changed, 76 insertions(+), 25 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 00f6213110e76..71f6e315ecd34 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -6740,23 +6740,16 @@ def nsmallest(self, n, columns, keep: str = "first") -> DataFrame: self, n=n, keep=keep, columns=columns ).nsmallest() - def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame: - """ - Swap levels i and j in a MultiIndex on a particular axis. - - Parameters - ---------- - i, j : int or str - Levels of the indices to be swapped. Can pass level name as string. - axis : {0 or 'index', 1 or 'columns'}, default 0 + @doc( + Series.swaplevel, + klass=_shared_doc_kwargs["klass"], + extra_params=dedent( + """axis : {0 or 'index', 1 or 'columns'}, default 0 The axis to swap levels on. 0 or 'index' for row-wise, 1 or - 'columns' for column-wise. - - Returns - ------- - DataFrame - - Examples + 'columns' for column-wise.""" + ), + examples=dedent( + """Examples -------- >>> df = pd.DataFrame( ... {"Grade": ["A", "B", "A", "C"]}, @@ -6805,8 +6798,10 @@ def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame: History Final exam January A Geography Final exam February B History Coursework March A - Geography Coursework April C - """ + Geography Coursework April C""" + ), + ) + def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame: result = self.copy() axis = self._get_axis_number(axis) diff --git a/pandas/core/series.py b/pandas/core/series.py index e94689383100d..10df6cb516563 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3863,23 +3863,79 @@ def nsmallest(self, n: int = 5, keep: str = "first") -> Series: """ return algorithms.SelectNSeries(self, n=n, keep=keep).nsmallest() + @doc( + klass=_shared_doc_kwargs["klass"], + extra_params=dedent( + """copy : bool, default True + Whether to copy underlying data.""" + ), + examples=dedent( + """Examples + -------- + >>> s = pd.Series( + ... ["A", "B", "A", "C"], + ... index=[ + ... ["Final exam", "Final exam", "Coursework", "Coursework"], + ... ["History", "Geography", "History", "Geography"], + ... ["January", "February", "March", "April"], + ... ], + ... ) + >>> s + Final exam History January A + Geography February B + Coursework History March A + Geography April C + + In the following example, we will swap the levels of the indices. + Here, we will swap the levels column-wise, but levels can be swapped row-wise + in a similar manner. Note that column-wise is the default behaviour. + By not supplying any arguments for i and j, we swap the last and second to + last indices. + + >>> s.swaplevel() + Final exam January History A + February Geography B + Coursework March History A + April Geography C + + By supplying one argument, we can choose which index to swap the last + index with. We can for example swap the first index with the last one as + follows. + + >>> s.swaplevel(0) + January History Final exam A + February Geography Final exam B + March History Coursework A + April Geography Coursework C + + We can also define explicitly which indices we want to swap by supplying values + for both i and j. Here, we for example swap the first and second indices. + + >>> s.swaplevel(0, 1) + History Final exam January A + Geography Final exam February B + History Coursework March A + Geography Coursework April C""" + ), + ) def swaplevel(self, i=-2, j=-1, copy=True) -> Series: """ - Swap levels i and j in a :class:`MultiIndex`. + Swap levels i and j in a :class:`MultiIndex` on a particular axis. Default is to swap the two innermost levels of the index. Parameters ---------- - i, j : int, str - Level of the indices to be swapped. Can pass level name as string. - copy : bool, default True - Whether to copy underlying data. + i, j : int or str + Levels of the indices to be swapped. Can pass level name as string. + {extra_params} Returns ------- - Series - Series with levels swapped in MultiIndex. + {klass} + {klass} with levels swapped in MultiIndex. + + {examples} """ assert isinstance(self.index, MultiIndex) new_index = self.index.swaplevel(i, j) From 94e5d8e18c38902837cd1f89f10d9404fc67bdb5 Mon Sep 17 00:00:00 2001 From: Gesa Stupperich Date: Sun, 20 Jun 2021 17:59:20 +0100 Subject: [PATCH 2/2] DOC: Add dtype to example output (#42120) --- pandas/core/series.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 10df6cb516563..90582bebafc4d 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3885,6 +3885,7 @@ def nsmallest(self, n: int = 5, keep: str = "first") -> Series: Geography February B Coursework History March A Geography April C + dtype: object In the following example, we will swap the levels of the indices. Here, we will swap the levels column-wise, but levels can be swapped row-wise @@ -3897,6 +3898,7 @@ def nsmallest(self, n: int = 5, keep: str = "first") -> Series: February Geography B Coursework March History A April Geography C + dtype: object By supplying one argument, we can choose which index to swap the last index with. We can for example swap the first index with the last one as @@ -3907,6 +3909,7 @@ def nsmallest(self, n: int = 5, keep: str = "first") -> Series: February Geography Final exam B March History Coursework A April Geography Coursework C + dtype: object We can also define explicitly which indices we want to swap by supplying values for both i and j. Here, we for example swap the first and second indices. @@ -3915,12 +3918,13 @@ def nsmallest(self, n: int = 5, keep: str = "first") -> Series: History Final exam January A Geography Final exam February B History Coursework March A - Geography Coursework April C""" + Geography Coursework April C + dtype: object""" ), ) def swaplevel(self, i=-2, j=-1, copy=True) -> Series: """ - Swap levels i and j in a :class:`MultiIndex` on a particular axis. + Swap levels i and j in a :class:`MultiIndex`. Default is to swap the two innermost levels of the index.