From eb7fd7418d0e16022eb7eaf781b03567ae22bfdb Mon Sep 17 00:00:00 2001 From: Jenna Vergeynst Date: Sat, 10 Mar 2018 16:13:48 +0100 Subject: [PATCH 1/5] DOC: Improved docstring of Series.idxmax and Series.idxmin --- pandas/core/series.py | 75 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 9 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 069f0372ab6e1..ae93b2d2e8503 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1326,18 +1326,26 @@ def duplicated(self, keep='first'): def idxmin(self, axis=None, skipna=True, *args, **kwargs): """ - Index *label* of the first occurrence of minimum of values. + Index label of the first occurrence of minimum of values. + + Look for the first occurence of maximum of values and return the + index label. When data contains NA/null values, return nan. Parameters ---------- skipna : boolean, default True Exclude NA/null values. If the entire Series is NA, the result will be NA. + axis : int, default 0 + Redundant for application on series. + *args, **kwargs : + Additional keywors have no effect but might be accepted + for compatibility with numpy. Raises ------ ValueError - * If the Series is empty + If the Series is empty Returns ------- @@ -1351,8 +1359,28 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): See Also -------- - DataFrame.idxmin - numpy.ndarray.argmin + numpy.ndarray.argmin : Return indices of the minimum values + along the given axis. + DataFrame.idxmin : Return index of first occurrence of minimum + over requested axis. + Series.idxmax : Return index *label* of the first occurrence + of maximum of values. + + Examples + -------- + >>> s = pd.Series(data=[1,None,4,1], index=['A','B','C','D']) + >>> s + A 1.0 + B NaN + C 4.0 + D 1.0 + dtype: float64 + + >>> s.idxmin() + 'A' + + s.idxmin(skipna=False) + nan """ skipna = nv.validate_argmin_with_skipna(skipna, args, kwargs) i = nanops.nanargmin(com._values_from_object(self), skipna=skipna) @@ -1360,20 +1388,28 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): return np.nan return self.index[i] - def idxmax(self, axis=None, skipna=True, *args, **kwargs): + def idxmax(self, axis=0, skipna=True, *args, **kwargs): """ - Index *label* of the first occurrence of maximum of values. + Return index label of the first occurrence of maximum of values. + + Look for the first occurence of maximum of values and return the + index label. When data contains NA/null values, return nan. Parameters ---------- skipna : boolean, default True Exclude NA/null values. If the entire Series is NA, the result will be NA. + axis : int, default 0 + Redundant for application on series. + *args, **kwargs : + Additional keywors have no effect but might be accepted + for compatibility with numpy. Raises ------ ValueError - * If the Series is empty + If the Series is empty Returns ------- @@ -1387,8 +1423,29 @@ def idxmax(self, axis=None, skipna=True, *args, **kwargs): See Also -------- - DataFrame.idxmax - numpy.ndarray.argmax + numpy.ndarray.argmax : Return indices of the maximum values + along the given axis. + DataFrame.idxmax : Return index of first occurrence of maximum + over requested axis. + Series.idxmin : Return index *label* of the first occurrence + of minimum of values. + + Examples + -------- + >>> s = pd.Series(data=[1,None,4,3,4], index=['A','B','C','D','E']) + >>> s + A 1.0 + B NaN + C 4.0 + D 3.0 + E 4.0 + dtype: float64 + + >>> s.idxmax() + 'C' + + s.idxmax(skipna=False) + nan """ skipna = nv.validate_argmax_with_skipna(skipna, args, kwargs) i = nanops.nanargmax(com._values_from_object(self), skipna=skipna) From fbe7b530103ab928b02cda69f8a370cef1c05735 Mon Sep 17 00:00:00 2001 From: Jenna Vergeynst Date: Sun, 11 Mar 2018 14:47:16 +0100 Subject: [PATCH 2/5] update docstrings --- pandas/core/series.py | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index ae93b2d2e8503..b4b52d8f40fe2 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1328,9 +1328,6 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): """ Index label of the first occurrence of minimum of values. - Look for the first occurence of maximum of values and return the - index label. When data contains NA/null values, return nan. - Parameters ---------- skipna : boolean, default True @@ -1359,7 +1356,7 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): See Also -------- - numpy.ndarray.argmin : Return indices of the minimum values + numpy.argmin : Return indices of the minimum values along the given axis. DataFrame.idxmin : Return index of first occurrence of minimum over requested axis. @@ -1368,7 +1365,8 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): Examples -------- - >>> s = pd.Series(data=[1,None,4,1], index=['A','B','C','D']) + >>> s = pd.Series(data=[1, None, 4, 1], + ... index=['A' ,'B' ,'C' ,'D']) >>> s A 1.0 B NaN @@ -1379,7 +1377,10 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): >>> s.idxmin() 'A' - s.idxmin(skipna=False) + If skipna=False and there is an NA value in the data, + the function returns nan. + + >>> s.idxmin(skipna=False) nan """ skipna = nv.validate_argmin_with_skipna(skipna, args, kwargs) @@ -1392,9 +1393,6 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): """ Return index label of the first occurrence of maximum of values. - Look for the first occurence of maximum of values and return the - index label. When data contains NA/null values, return nan. - Parameters ---------- skipna : boolean, default True @@ -1423,7 +1421,7 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): See Also -------- - numpy.ndarray.argmax : Return indices of the maximum values + numpy.argmax : Return indices of the maximum values along the given axis. DataFrame.idxmax : Return index of first occurrence of maximum over requested axis. @@ -1432,7 +1430,8 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): Examples -------- - >>> s = pd.Series(data=[1,None,4,3,4], index=['A','B','C','D','E']) + >>> s = pd.Series(data=[1, None, 4, 3, 4], + ... index=['A', 'B', 'C', 'D', 'E']) >>> s A 1.0 B NaN @@ -1444,7 +1443,10 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): >>> s.idxmax() 'C' - s.idxmax(skipna=False) + If skipna=False and there is an NA value in the data, + the function returns nan. + + >>> s.idxmax(skipna=False) nan """ skipna = nv.validate_argmax_with_skipna(skipna, args, kwargs) From f8491ffe5888a3238191bef6bdb82aef29a7efc3 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 12 Mar 2018 12:26:36 -0500 Subject: [PATCH 3/5] Updated. --- pandas/core/series.py | 48 +++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index b4b52d8f40fe2..4a3a66b64dd5b 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1326,7 +1326,10 @@ def duplicated(self, keep='first'): def idxmin(self, axis=None, skipna=True, *args, **kwargs): """ - Index label of the first occurrence of minimum of values. + Return the row label of the minimum value. + + If multiple values equal the minimum, the first row label with that + value is returned. Parameters ---------- @@ -1334,19 +1337,20 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): Exclude NA/null values. If the entire Series is NA, the result will be NA. axis : int, default 0 - Redundant for application on series. - *args, **kwargs : + For compatibility with DataFrame.idxmin. Redundant for application + on Series. + *args, **kwargs Additional keywors have no effect but might be accepted - for compatibility with numpy. + for compatibility with NumPy. + + Returns + ------- + idxmin : Index of minimum of values. Raises ------ ValueError - If the Series is empty - - Returns - ------- - idxmin : Index of minimum of values + If the Series is empty. Notes ----- @@ -1378,7 +1382,7 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): 'A' If skipna=False and there is an NA value in the data, - the function returns nan. + the function returns ``nan``. >>> s.idxmin(skipna=False) nan @@ -1391,7 +1395,10 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): def idxmax(self, axis=0, skipna=True, *args, **kwargs): """ - Return index label of the first occurrence of maximum of values. + Return the row label of the maximum value. + + If multiple values equal the maximum, the first row label with that + value is returned. Parameters ---------- @@ -1399,19 +1406,20 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): Exclude NA/null values. If the entire Series is NA, the result will be NA. axis : int, default 0 - Redundant for application on series. - *args, **kwargs : + For compatibility with DataFrame.idxmax. Redundant for application + on Series. + *args, **kwargs Additional keywors have no effect but might be accepted - for compatibility with numpy. + for compatibility with NumPy. + + Returns + ------- + idxmax : Index of maximum of values. Raises ------ ValueError - If the Series is empty - - Returns - ------- - idxmax : Index of maximum of values + If the Series is empty. Notes ----- @@ -1444,7 +1452,7 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): 'C' If skipna=False and there is an NA value in the data, - the function returns nan. + the function returns ``nan``. >>> s.idxmax(skipna=False) nan From 39e8cec9a1bf7dc95ac242625bc41e01c6e1831c Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 12 Mar 2018 12:29:14 -0500 Subject: [PATCH 4/5] quoting --- pandas/core/series.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 4a3a66b64dd5b..58ca344270cee 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1381,7 +1381,7 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): >>> s.idxmin() 'A' - If skipna=False and there is an NA value in the data, + If 'skipna' is False and there is an NA value in the data, the function returns ``nan``. >>> s.idxmin(skipna=False) @@ -1451,7 +1451,7 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): >>> s.idxmax() 'C' - If skipna=False and there is an NA value in the data, + If 'skipna' is False and there is an NA value in the data, the function returns ``nan``. >>> s.idxmax(skipna=False) From 41394ae6a00d0601303b0faf05afb1ea463fbf17 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 12 Mar 2018 12:30:11 -0500 Subject: [PATCH 5/5] Correct quoting --- pandas/core/series.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 58ca344270cee..3c045760ba56b 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1381,7 +1381,7 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs): >>> s.idxmin() 'A' - If 'skipna' is False and there is an NA value in the data, + If `skipna` is False and there is an NA value in the data, the function returns ``nan``. >>> s.idxmin(skipna=False) @@ -1451,7 +1451,7 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs): >>> s.idxmax() 'C' - If 'skipna' is False and there is an NA value in the data, + If `skipna` is False and there is an NA value in the data, the function returns ``nan``. >>> s.idxmax(skipna=False)