DOC: update the pandas.DataFrame.clip docstring

pandas/core/generic.py

@@ -5601,53 +5601,99 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
         """
         Trim values at input threshold(s).
 
+        Elements above the upper threshold will be changed to upper threshold.
+        Elements below the lower threshold will be changed to lower threshold.
+
         Parameters
         ----------
         lower : float or array_like, default None
+            Lower threshold for clipping.  Values smaller than upper will be
+            converted to lower.
         upper : float or array_like, default None
+            Upper threshold for clipping.  Values larger than upper will be
+            converted to upper.
         axis : int or string axis name, optional
             Align object with lower and upper along the given axis.
         inplace : boolean, default False
             Whether to perform the operation in place on the data
-                .. versionadded:: 0.21.0
+                .. versionadded:: 0.21.0.
+        args : dictionary of arguments arguments passed to pandas.compat.numpy
+        kwargs : dictionary of keyword arguments passed to pandas.compat.numpy
 
         Returns
         -------
-        clipped : Series
+        clipped : DataFrame/Series
+            Elements above or below the upper and lower thresholds converted to
+            threshold values.
+
+        Notes
+        -----
+        Clipping data is a method for dealing with dubious elements.
+        If some elements are too large or too small, clipping is one way to
+        transform the data into a reasonable range.
+
+        See Also
+        --------
+        pandas.DataFrame.clip_upper : Return copy of input with values
+            above given value(s) truncated.
+        pandas.DataFrame.clip_lower : Return copy of input with values
+            below given value(s) truncated.
 
         Examples
         --------
+        >>> df=pd.DataFrame({'a':[1, 2, 3], 'b':[4, 5, 6], 'c':[7, 8, 9001]})
         >>> df
-                  0         1
-        0  0.335232 -1.256177
-        1 -1.367855  0.746646
-        2  0.027753 -1.176076
-        3  0.230930 -0.679613
-        4  1.261967  0.570967
-
-        >>> df.clip(-1.0, 0.5)
-                  0         1
-        0  0.335232 -1.000000
-        1 -1.000000  0.500000
-        2  0.027753 -1.000000
-        3  0.230930 -0.679613
-        4  0.500000  0.500000
-
-        >>> t
-        0   -0.3
-        1   -0.2
-        2   -0.1
-        3    0.0
-        4    0.1
-        dtype: float64
-
-        >>> df.clip(t, t + 1, axis=0)
-                  0         1
-        0  0.335232 -0.300000
-        1 -0.200000  0.746646
-        2  0.027753 -0.100000
-        3  0.230930  0.000000
-        4  1.100000  0.570967
+            a   b   c
+        0   1   4   7
+        1   2   5   8
+        2   3   6   9001
+
+        >>> df.clip(lower=1, upper=9)
+            a   b   c
+        0   1   4   7
+        1   2   5   8
+        2   3   6   9
+
+        You can clip each column or row with different thresholds by passing
+        a ``Series`` to the lower/upper argument.
+
+        >>> some_data={'A':[-19, 12, -5],'B':[1, 100, -5]}
+        >>> df=pd.DataFrame(data=some_data, index=['foo', 'bar', 'bizz'])
+        >>> df
+              A   B
+        foo  -19  1
+        bar   12 100
+        bizz -5  -5
+
+        Use the axis argument to clip by column or rows.  Clip column A with
+        lower threshold of -10 and column B has lower threshold of 10.
+
+        >>> df.clip(lower=pd.Series({'A':-10, 'B':10}), axis=1)
+              A   B
+        foo  -10 10
+        bar   12 100
+        bizz -5  10
+
+        Clip the foo, bar, and bizz rows with lower thresholds -10, 0, and 10.
+
+        >>> row_thresh=pd.Series({'foo':-10, 'bar':0, 'bizz':10})
+        >>> df.clip(lower=row_thresh, axis=0)
+             A   B
+        foo  -10 1
+        bar   12 100
+        bizz  10 10
+
+        `Winsorizing <https://en.wikipedia.org/wiki/Winsorizing>`__ is a way
+        of removing outliers from data.  Columns of a DataFrame can be
+        winsorized by using clip.
+
+        >>> import numpy as np
+        >>> x=np.random.normal(size=(1000,3))
+        >>> df=pd.DataFrame(x, columns=['a','b','c'])
+        >>> #Winsorize columns at 5% and 95%
+        >>> U=df.quantile(0.95)
+        >>> L=df.quantile(0.5)
+        >>> winsorized_df=df.clip(lower=L, upper=U, axis = 1)
         """
         if isinstance(self, ABCPanel):
             raise NotImplementedError("clip is not supported yet for panels")