Skip to content

Commit eb7fd74

Browse files
DOC: Improved docstring of Series.idxmax and Series.idxmin
1 parent 9119d07 commit eb7fd74

File tree

1 file changed

+66
-9
lines changed

1 file changed

+66
-9
lines changed

pandas/core/series.py

Lines changed: 66 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1326,18 +1326,26 @@ def duplicated(self, keep='first'):
13261326

13271327
def idxmin(self, axis=None, skipna=True, *args, **kwargs):
13281328
"""
1329-
Index *label* of the first occurrence of minimum of values.
1329+
Index label of the first occurrence of minimum of values.
1330+
1331+
Look for the first occurence of maximum of values and return the
1332+
index label. When data contains NA/null values, return nan.
13301333
13311334
Parameters
13321335
----------
13331336
skipna : boolean, default True
13341337
Exclude NA/null values. If the entire Series is NA, the result
13351338
will be NA.
1339+
axis : int, default 0
1340+
Redundant for application on series.
1341+
*args, **kwargs :
1342+
Additional keywors have no effect but might be accepted
1343+
for compatibility with numpy.
13361344
13371345
Raises
13381346
------
13391347
ValueError
1340-
* If the Series is empty
1348+
If the Series is empty
13411349
13421350
Returns
13431351
-------
@@ -1351,29 +1359,57 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs):
13511359
13521360
See Also
13531361
--------
1354-
DataFrame.idxmin
1355-
numpy.ndarray.argmin
1362+
numpy.ndarray.argmin : Return indices of the minimum values
1363+
along the given axis.
1364+
DataFrame.idxmin : Return index of first occurrence of minimum
1365+
over requested axis.
1366+
Series.idxmax : Return index *label* of the first occurrence
1367+
of maximum of values.
1368+
1369+
Examples
1370+
--------
1371+
>>> s = pd.Series(data=[1,None,4,1], index=['A','B','C','D'])
1372+
>>> s
1373+
A 1.0
1374+
B NaN
1375+
C 4.0
1376+
D 1.0
1377+
dtype: float64
1378+
1379+
>>> s.idxmin()
1380+
'A'
1381+
1382+
s.idxmin(skipna=False)
1383+
nan
13561384
"""
13571385
skipna = nv.validate_argmin_with_skipna(skipna, args, kwargs)
13581386
i = nanops.nanargmin(com._values_from_object(self), skipna=skipna)
13591387
if i == -1:
13601388
return np.nan
13611389
return self.index[i]
13621390

1363-
def idxmax(self, axis=None, skipna=True, *args, **kwargs):
1391+
def idxmax(self, axis=0, skipna=True, *args, **kwargs):
13641392
"""
1365-
Index *label* of the first occurrence of maximum of values.
1393+
Return index label of the first occurrence of maximum of values.
1394+
1395+
Look for the first occurence of maximum of values and return the
1396+
index label. When data contains NA/null values, return nan.
13661397
13671398
Parameters
13681399
----------
13691400
skipna : boolean, default True
13701401
Exclude NA/null values. If the entire Series is NA, the result
13711402
will be NA.
1403+
axis : int, default 0
1404+
Redundant for application on series.
1405+
*args, **kwargs :
1406+
Additional keywors have no effect but might be accepted
1407+
for compatibility with numpy.
13721408
13731409
Raises
13741410
------
13751411
ValueError
1376-
* If the Series is empty
1412+
If the Series is empty
13771413
13781414
Returns
13791415
-------
@@ -1387,8 +1423,29 @@ def idxmax(self, axis=None, skipna=True, *args, **kwargs):
13871423
13881424
See Also
13891425
--------
1390-
DataFrame.idxmax
1391-
numpy.ndarray.argmax
1426+
numpy.ndarray.argmax : Return indices of the maximum values
1427+
along the given axis.
1428+
DataFrame.idxmax : Return index of first occurrence of maximum
1429+
over requested axis.
1430+
Series.idxmin : Return index *label* of the first occurrence
1431+
of minimum of values.
1432+
1433+
Examples
1434+
--------
1435+
>>> s = pd.Series(data=[1,None,4,3,4], index=['A','B','C','D','E'])
1436+
>>> s
1437+
A 1.0
1438+
B NaN
1439+
C 4.0
1440+
D 3.0
1441+
E 4.0
1442+
dtype: float64
1443+
1444+
>>> s.idxmax()
1445+
'C'
1446+
1447+
s.idxmax(skipna=False)
1448+
nan
13921449
"""
13931450
skipna = nv.validate_argmax_with_skipna(skipna, args, kwargs)
13941451
i = nanops.nanargmax(com._values_from_object(self), skipna=skipna)

0 commit comments

Comments
 (0)