Skip to content

Commit 59c6dd4

Browse files
JennaVergeynstTomAugspurger
authored andcommitted
DOC: update the Seriex.idxmax and Series.idxmin docstring (#20174)
* DOC: Improved docstring of Series.idxmax and Series.idxmin * update docstrings * Updated. * quoting * Correct quoting
1 parent 0ed9916 commit 59c6dd4

File tree

1 file changed

+84
-17
lines changed

1 file changed

+84
-17
lines changed

pandas/core/series.py

Lines changed: 84 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1460,22 +1460,31 @@ def duplicated(self, keep='first'):
14601460

14611461
def idxmin(self, axis=None, skipna=True, *args, **kwargs):
14621462
"""
1463-
Index *label* of the first occurrence of minimum of values.
1463+
Return the row label of the minimum value.
1464+
1465+
If multiple values equal the minimum, the first row label with that
1466+
value is returned.
14641467
14651468
Parameters
14661469
----------
14671470
skipna : boolean, default True
14681471
Exclude NA/null values. If the entire Series is NA, the result
14691472
will be NA.
1473+
axis : int, default 0
1474+
For compatibility with DataFrame.idxmin. Redundant for application
1475+
on Series.
1476+
*args, **kwargs
1477+
Additional keywors have no effect but might be accepted
1478+
for compatibility with NumPy.
1479+
1480+
Returns
1481+
-------
1482+
idxmin : Index of minimum of values.
14701483
14711484
Raises
14721485
------
14731486
ValueError
1474-
* If the Series is empty
1475-
1476-
Returns
1477-
-------
1478-
idxmin : Index of minimum of values
1487+
If the Series is empty.
14791488
14801489
Notes
14811490
-----
@@ -1485,33 +1494,66 @@ def idxmin(self, axis=None, skipna=True, *args, **kwargs):
14851494
14861495
See Also
14871496
--------
1488-
DataFrame.idxmin
1489-
numpy.ndarray.argmin
1497+
numpy.argmin : Return indices of the minimum values
1498+
along the given axis.
1499+
DataFrame.idxmin : Return index of first occurrence of minimum
1500+
over requested axis.
1501+
Series.idxmax : Return index *label* of the first occurrence
1502+
of maximum of values.
1503+
1504+
Examples
1505+
--------
1506+
>>> s = pd.Series(data=[1, None, 4, 1],
1507+
... index=['A' ,'B' ,'C' ,'D'])
1508+
>>> s
1509+
A 1.0
1510+
B NaN
1511+
C 4.0
1512+
D 1.0
1513+
dtype: float64
1514+
1515+
>>> s.idxmin()
1516+
'A'
1517+
1518+
If `skipna` is False and there is an NA value in the data,
1519+
the function returns ``nan``.
1520+
1521+
>>> s.idxmin(skipna=False)
1522+
nan
14901523
"""
14911524
skipna = nv.validate_argmin_with_skipna(skipna, args, kwargs)
14921525
i = nanops.nanargmin(com._values_from_object(self), skipna=skipna)
14931526
if i == -1:
14941527
return np.nan
14951528
return self.index[i]
14961529

1497-
def idxmax(self, axis=None, skipna=True, *args, **kwargs):
1530+
def idxmax(self, axis=0, skipna=True, *args, **kwargs):
14981531
"""
1499-
Index *label* of the first occurrence of maximum of values.
1532+
Return the row label of the maximum value.
1533+
1534+
If multiple values equal the maximum, the first row label with that
1535+
value is returned.
15001536
15011537
Parameters
15021538
----------
15031539
skipna : boolean, default True
15041540
Exclude NA/null values. If the entire Series is NA, the result
15051541
will be NA.
1542+
axis : int, default 0
1543+
For compatibility with DataFrame.idxmax. Redundant for application
1544+
on Series.
1545+
*args, **kwargs
1546+
Additional keywors have no effect but might be accepted
1547+
for compatibility with NumPy.
1548+
1549+
Returns
1550+
-------
1551+
idxmax : Index of maximum of values.
15061552
15071553
Raises
15081554
------
15091555
ValueError
1510-
* If the Series is empty
1511-
1512-
Returns
1513-
-------
1514-
idxmax : Index of maximum of values
1556+
If the Series is empty.
15151557
15161558
Notes
15171559
-----
@@ -1521,8 +1563,33 @@ def idxmax(self, axis=None, skipna=True, *args, **kwargs):
15211563
15221564
See Also
15231565
--------
1524-
DataFrame.idxmax
1525-
numpy.ndarray.argmax
1566+
numpy.argmax : Return indices of the maximum values
1567+
along the given axis.
1568+
DataFrame.idxmax : Return index of first occurrence of maximum
1569+
over requested axis.
1570+
Series.idxmin : Return index *label* of the first occurrence
1571+
of minimum of values.
1572+
1573+
Examples
1574+
--------
1575+
>>> s = pd.Series(data=[1, None, 4, 3, 4],
1576+
... index=['A', 'B', 'C', 'D', 'E'])
1577+
>>> s
1578+
A 1.0
1579+
B NaN
1580+
C 4.0
1581+
D 3.0
1582+
E 4.0
1583+
dtype: float64
1584+
1585+
>>> s.idxmax()
1586+
'C'
1587+
1588+
If `skipna` is False and there is an NA value in the data,
1589+
the function returns ``nan``.
1590+
1591+
>>> s.idxmax(skipna=False)
1592+
nan
15261593
"""
15271594
skipna = nv.validate_argmax_with_skipna(skipna, args, kwargs)
15281595
i = nanops.nanargmax(com._values_from_object(self), skipna=skipna)

0 commit comments

Comments
 (0)