Repository: pandas-dev/pandas

Issue:
DOC: docstring for min max should point out idxmax and idxmin
Numpy users might be puzzled by the fact that everything is so numpy-like, but argmax and argmin are not implemented (of course having not read the manual), so I would like to suggest to point out idxmax and idxmin in the docstring of Series/DataFrame.max/min?



Discussion:

Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/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)
diff --git a/pandas/core/series.py b/pandas/core/series.py
--- a/pandas/core/series.py
+++ b/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:


Test patch: