Merge pull request #9769 from alfonsomhc/patch-1

Added documentation for mode()

Author: shoyer

pandas/core/frame.py

@@ -4411,9 +4411,15 @@ def _get_agg_axis(self, axis_num):
 
     def mode(self, axis=0, numeric_only=False):
         """
-        Gets the mode of each element along the axis selected. Empty if nothing
+        Gets the mode(s) of each element along the axis selected. Empty if nothing
         has 2+ occurrences. Adds a row for each mode per label, fills in gaps
-        with nan.
+        with nan. 
+        
+        Note that there could be multiple values returned for the selected
+        axis (when more than one item share the maximum frequency), which is the 
+        reason why a dataframe is returned. If you want to impute missing values 
+        with the mode in a dataframe ``df``, you can just do this: 
+        ``df.fillna(df.mode().iloc[0])``
 
         Parameters
         ----------
@@ -4426,6 +4432,14 @@ def mode(self, axis=0, numeric_only=False):
         Returns
         -------
         modes : DataFrame (sorted)
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2, 1, 2, 1, 2, 3]})
+        >>> df.mode()
+           A
+        0  1
+        1  2
         """
         data = self if not numeric_only else self._get_numeric_data()
         f = lambda s: s.mode()