Merge pull request #3580 from cpcloud/argminmax-doc-3574

DOC: add mention of idx* methods in max/min methods of Series/DataFrame

Author: jreback

doc/source/basics.rst

@@ -401,6 +401,10 @@ value, ``idxmin`` and ``idxmax`` return the first matching index:
    df3
    df3['A'].idxmin()
 
+.. note::
+
+   ``idxmin`` and ``idxmax`` are called ``argmin`` and ``argmax`` in NumPy.
+
 .. _basics.discretization:
 
 Value counts (histogramming)

pandas/core/frame.py

@@ -4770,6 +4770,18 @@ def mean(self, axis=0, skipna=True, level=None):
                   extras='')
     @Appender(_stat_doc)
     def min(self, axis=0, skipna=True, level=None):
+        """
+        Notes
+        -----
+        This method returns the minimum of the values in the DataFrame. If you
+        want the *index* of the minimum, use ``DataFrame.idxmin``. This is the
+        equivalent of the ``numpy.ndarray`` method ``argmin``.
+
+        See Also
+        --------
+        DataFrame.idxmin
+        Series.idxmin
+        """
         if level is not None:
             return self._agg_by_level('min', axis=axis, level=level,
                                       skipna=skipna)
@@ -4780,6 +4792,18 @@ def min(self, axis=0, skipna=True, level=None):
                   extras='')
     @Appender(_stat_doc)
     def max(self, axis=0, skipna=True, level=None):
+        """
+        Notes
+        -----
+        This method returns the maximum of the values in the DataFrame. If you
+        want the *index* of the maximum, use ``DataFrame.idxmax``. This is the
+        equivalent of the ``numpy.ndarray`` method ``argmax``.
+
+        See Also
+        --------
+        DataFrame.idxmax
+        Series.idxmax
+        """
         if level is not None:
             return self._agg_by_level('max', axis=axis, level=level,
                                       skipna=skipna)
@@ -4939,6 +4963,14 @@ def idxmin(self, axis=0, skipna=True):
         Returns
         -------
         idxmin : Series
+
+        Notes
+        -----
+        This method is the DataFrame version of ``ndarray.argmin``.
+
+        See Also
+        --------
+        Series.idxmin
         """
         axis = self._get_axis_number(axis)
         indices = nanops.nanargmin(self.values, axis=axis, skipna=skipna)
@@ -4962,6 +4994,14 @@ def idxmax(self, axis=0, skipna=True):
         Returns
         -------
         idxmax : Series
+
+        Notes
+        -----
+        This method is the DataFrame version of ``ndarray.argmax``.
+
+        See Also
+        --------
+        Series.idxmax
         """
         axis = self._get_axis_number(axis)
         indices = nanops.nanargmax(self.values, axis=axis, skipna=skipna)

pandas/core/series.py

@@ -1516,6 +1516,18 @@ def mad(self, skipna=True, level=None):
                   na_action=_doc_exclude_na, extras='')
     @Appender(_stat_doc)
     def min(self, axis=None, out=None, skipna=True, level=None):
+        """
+        Notes
+        -----
+        This method returns the minimum of the values in the Series. If you
+        want the *index* of the minimum, use ``Series.idxmin``. This is the
+        equivalent of the ``numpy.ndarray`` method ``argmin``.
+
+        See Also
+        --------
+        Series.idxmin
+        DataFrame.idxmin
+        """
         if level is not None:
             return self._agg_by_level('min', level=level, skipna=skipna)
         return nanops.nanmin(self.values, skipna=skipna)
@@ -1524,6 +1536,18 @@ def min(self, axis=None, out=None, skipna=True, level=None):
                   na_action=_doc_exclude_na, extras='')
     @Appender(_stat_doc)
     def max(self, axis=None, out=None, skipna=True, level=None):
+        """
+        Notes
+        -----
+        This method returns the maximum of the values in the Series. If you
+        want the *index* of the maximum, use ``Series.idxmax``. This is the
+        equivalent of the ``numpy.ndarray`` method ``argmax``.
+
+        See Also
+        --------
+        Series.idxmax
+        DataFrame.idxmax
+        """
         if level is not None:
             return self._agg_by_level('max', level=level, skipna=skipna)
         return nanops.nanmax(self.values, skipna=skipna)
@@ -1592,6 +1616,14 @@ def idxmin(self, axis=None, out=None, skipna=True):
         Returns
         -------
         idxmin : Index of minimum of values
+
+        Notes
+        -----
+        This method is the Series version of ``ndarray.argmin``.
+
+        See Also
+        --------
+        DataFrame.idxmin
         """
         i = nanops.nanargmin(self.values, skipna=skipna)
         if i == -1:
@@ -1610,6 +1642,14 @@ def idxmax(self, axis=None, out=None, skipna=True):
         Returns
         -------
         idxmax : Index of minimum of values
+
+        Notes
+        -----
+        This method is the Series version of ``ndarray.argmax``.
+
+        See Also
+        --------
+        DataFrame.idxmax
         """
         i = nanops.nanargmax(self.values, skipna=skipna)
         if i == -1: