Skip to content

Commit e29444b

Browse files
authored
DOC: Move idxmin/idxmax docstrings to shared docs (#46729)
1 parent a59582d commit e29444b

File tree

3 files changed

+131
-122
lines changed

3 files changed

+131
-122
lines changed

pandas/core/frame.py

+2-120
Original file line numberDiff line numberDiff line change
@@ -10536,67 +10536,8 @@ def nunique(self, axis: Axis = 0, dropna: bool = True) -> Series:
1053610536
"""
1053710537
return self.apply(Series.nunique, axis=axis, dropna=dropna)
1053810538

10539+
@doc(_shared_docs["idxmin"])
1053910540
def idxmin(self, axis: Axis = 0, skipna: bool = True) -> Series:
10540-
"""
10541-
Return index of first occurrence of minimum over requested axis.
10542-
10543-
NA/null values are excluded.
10544-
10545-
Parameters
10546-
----------
10547-
axis : {0 or 'index', 1 or 'columns'}, default 0
10548-
The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
10549-
skipna : bool, default True
10550-
Exclude NA/null values. If an entire row/column is NA, the result
10551-
will be NA.
10552-
10553-
Returns
10554-
-------
10555-
Series
10556-
Indexes of minima along the specified axis.
10557-
10558-
Raises
10559-
------
10560-
ValueError
10561-
* If the row/column is empty
10562-
10563-
See Also
10564-
--------
10565-
Series.idxmin : Return index of the minimum element.
10566-
10567-
Notes
10568-
-----
10569-
This method is the DataFrame version of ``ndarray.argmin``.
10570-
10571-
Examples
10572-
--------
10573-
Consider a dataset containing food consumption in Argentina.
10574-
10575-
>>> df = pd.DataFrame({'consumption': [10.51, 103.11, 55.48],
10576-
... 'co2_emissions': [37.2, 19.66, 1712]},
10577-
... index=['Pork', 'Wheat Products', 'Beef'])
10578-
10579-
>>> df
10580-
consumption co2_emissions
10581-
Pork 10.51 37.20
10582-
Wheat Products 103.11 19.66
10583-
Beef 55.48 1712.00
10584-
10585-
By default, it returns the index for the minimum value in each column.
10586-
10587-
>>> df.idxmin()
10588-
consumption Pork
10589-
co2_emissions Wheat Products
10590-
dtype: object
10591-
10592-
To return the index for the minimum value in each row, use ``axis="columns"``.
10593-
10594-
>>> df.idxmin(axis="columns")
10595-
Pork consumption
10596-
Wheat Products co2_emissions
10597-
Beef consumption
10598-
dtype: object
10599-
"""
1060010541
axis = self._get_axis_number(axis)
1060110542

1060210543
res = self._reduce(
@@ -10613,67 +10554,8 @@ def idxmin(self, axis: Axis = 0, skipna: bool = True) -> Series:
1061310554
result = [index[i] if i >= 0 else np.nan for i in indices]
1061410555
return self._constructor_sliced(result, index=self._get_agg_axis(axis))
1061510556

10557+
@doc(_shared_docs["idxmax"])
1061610558
def idxmax(self, axis: Axis = 0, skipna: bool = True) -> Series:
10617-
"""
10618-
Return index of first occurrence of maximum over requested axis.
10619-
10620-
NA/null values are excluded.
10621-
10622-
Parameters
10623-
----------
10624-
axis : {0 or 'index', 1 or 'columns'}, default 0
10625-
The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
10626-
skipna : bool, default True
10627-
Exclude NA/null values. If an entire row/column is NA, the result
10628-
will be NA.
10629-
10630-
Returns
10631-
-------
10632-
Series
10633-
Indexes of maxima along the specified axis.
10634-
10635-
Raises
10636-
------
10637-
ValueError
10638-
* If the row/column is empty
10639-
10640-
See Also
10641-
--------
10642-
Series.idxmax : Return index of the maximum element.
10643-
10644-
Notes
10645-
-----
10646-
This method is the DataFrame version of ``ndarray.argmax``.
10647-
10648-
Examples
10649-
--------
10650-
Consider a dataset containing food consumption in Argentina.
10651-
10652-
>>> df = pd.DataFrame({'consumption': [10.51, 103.11, 55.48],
10653-
... 'co2_emissions': [37.2, 19.66, 1712]},
10654-
... index=['Pork', 'Wheat Products', 'Beef'])
10655-
10656-
>>> df
10657-
consumption co2_emissions
10658-
Pork 10.51 37.20
10659-
Wheat Products 103.11 19.66
10660-
Beef 55.48 1712.00
10661-
10662-
By default, it returns the index for the maximum value in each column.
10663-
10664-
>>> df.idxmax()
10665-
consumption Wheat Products
10666-
co2_emissions Beef
10667-
dtype: object
10668-
10669-
To return the index for the maximum value in each row, use ``axis="columns"``.
10670-
10671-
>>> df.idxmax(axis="columns")
10672-
Pork co2_emissions
10673-
Wheat Products consumption
10674-
Beef co2_emissions
10675-
dtype: object
10676-
"""
1067710559
axis = self._get_axis_number(axis)
1067810560

1067910561
res = self._reduce(

pandas/core/groupby/generic.py

+3-2
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@
8484
all_indexes_same,
8585
)
8686
from pandas.core.series import Series
87+
from pandas.core.shared_docs import _shared_docs
8788
from pandas.core.util.numba_ import maybe_use_numba
8889

8990
from pandas.plotting import boxplot_frame_groupby
@@ -1552,7 +1553,7 @@ def nunique(self, dropna: bool = True) -> DataFrame:
15521553

15531554
return results
15541555

1555-
@Appender(DataFrame.idxmax.__doc__)
1556+
@doc(_shared_docs["idxmax"])
15561557
def idxmax(self, axis=0, skipna: bool = True):
15571558
axis = DataFrame._get_axis_number(axis)
15581559
numeric_only = None if axis == 0 else False
@@ -1574,7 +1575,7 @@ def func(df):
15741575
func.__name__ = "idxmax"
15751576
return self._python_apply_general(func, self._obj_with_exclusions)
15761577

1577-
@Appender(DataFrame.idxmin.__doc__)
1578+
@doc(_shared_docs["idxmin"])
15781579
def idxmin(self, axis=0, skipna: bool = True):
15791580
axis = DataFrame._get_axis_number(axis)
15801581
numeric_only = None if axis == 0 else False

pandas/core/shared_docs.py

+126
Original file line numberDiff line numberDiff line change
@@ -734,3 +734,129 @@
734734
.. versionchanged:: 1.4.0
735735
Previously the explicit ``None`` was silently ignored.
736736
"""
737+
738+
_shared_docs[
739+
"idxmin"
740+
] = """
741+
Return index of first occurrence of minimum over requested axis.
742+
743+
NA/null values are excluded.
744+
745+
Parameters
746+
----------
747+
axis : {{0 or 'index', 1 or 'columns'}}, default 0
748+
The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
749+
skipna : bool, default True
750+
Exclude NA/null values. If an entire row/column is NA, the result
751+
will be NA.
752+
753+
Returns
754+
-------
755+
Series
756+
Indexes of minima along the specified axis.
757+
758+
Raises
759+
------
760+
ValueError
761+
* If the row/column is empty
762+
763+
See Also
764+
--------
765+
Series.idxmin : Return index of the minimum element.
766+
767+
Notes
768+
-----
769+
This method is the DataFrame version of ``ndarray.argmin``.
770+
771+
Examples
772+
--------
773+
Consider a dataset containing food consumption in Argentina.
774+
775+
>>> df = pd.DataFrame({{'consumption': [10.51, 103.11, 55.48],
776+
... 'co2_emissions': [37.2, 19.66, 1712]}},
777+
... index=['Pork', 'Wheat Products', 'Beef'])
778+
779+
>>> df
780+
consumption co2_emissions
781+
Pork 10.51 37.20
782+
Wheat Products 103.11 19.66
783+
Beef 55.48 1712.00
784+
785+
By default, it returns the index for the minimum value in each column.
786+
787+
>>> df.idxmin()
788+
consumption Pork
789+
co2_emissions Wheat Products
790+
dtype: object
791+
792+
To return the index for the minimum value in each row, use ``axis="columns"``.
793+
794+
>>> df.idxmin(axis="columns")
795+
Pork consumption
796+
Wheat Products co2_emissions
797+
Beef consumption
798+
dtype: object
799+
"""
800+
801+
_shared_docs[
802+
"idxmax"
803+
] = """
804+
Return index of first occurrence of maximum over requested axis.
805+
806+
NA/null values are excluded.
807+
808+
Parameters
809+
----------
810+
axis : {{0 or 'index', 1 or 'columns'}}, default 0
811+
The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
812+
skipna : bool, default True
813+
Exclude NA/null values. If an entire row/column is NA, the result
814+
will be NA.
815+
816+
Returns
817+
-------
818+
Series
819+
Indexes of maxima along the specified axis.
820+
821+
Raises
822+
------
823+
ValueError
824+
* If the row/column is empty
825+
826+
See Also
827+
--------
828+
Series.idxmax : Return index of the maximum element.
829+
830+
Notes
831+
-----
832+
This method is the DataFrame version of ``ndarray.argmax``.
833+
834+
Examples
835+
--------
836+
Consider a dataset containing food consumption in Argentina.
837+
838+
>>> df = pd.DataFrame({{'consumption': [10.51, 103.11, 55.48],
839+
... 'co2_emissions': [37.2, 19.66, 1712]}},
840+
... index=['Pork', 'Wheat Products', 'Beef'])
841+
842+
>>> df
843+
consumption co2_emissions
844+
Pork 10.51 37.20
845+
Wheat Products 103.11 19.66
846+
Beef 55.48 1712.00
847+
848+
By default, it returns the index for the maximum value in each column.
849+
850+
>>> df.idxmax()
851+
consumption Wheat Products
852+
co2_emissions Beef
853+
dtype: object
854+
855+
To return the index for the maximum value in each row, use ``axis="columns"``.
856+
857+
>>> df.idxmax(axis="columns")
858+
Pork co2_emissions
859+
Wheat Products consumption
860+
Beef co2_emissions
861+
dtype: object
862+
"""

0 commit comments

Comments
 (0)