DOC: update the pandas.DataFrame.clip docstring

pandas/core/generic.py

@@ -5601,53 +5601,98 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
         """
         Trim values at input threshold(s).
 
+        Elements above/below the upper/lower thresholds will be changed to
+        upper/lower thresholds.
+
         Parameters
         ----------
-        lower : float or array_like, default None
-        upper : float or array_like, default None
-        axis : int or string axis name, optional
+        lower : float, array-like or None, default None
+            Lower threshold for clipping.  Values smaller than `lower` will be
+            converted to `lower`.
+        upper : float, array-like or None, default None
+            Upper threshold for clipping.  Values larger than `upper` will be
+            converted to `upper`.
+        axis : {0 or 'index', 1 or 'columns', None}, default None
             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 : arguments passed to pandas.compat.numpy
+        **kwargs : keyword arguments passed to pandas.compat.numpy
 
         Returns
         -------
-        clipped : Series
+        clipped : `Series` or `DataFrame`.
+            Elements above or below the upper and lower thresholds converted to
+            threshold values.
+
+        Notes
+        -----
+        Clipping data is a method for dealing with out-of-range 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.
+        pandas.Series.clip : Trim values at input threshold(s).
 
         Examples
         --------
+        >>> some_data = {'a': [1, 2, 3], 'b': [4, 5, 6], 'c': [7, 8, 9001]}
+        >>> df = pd.DataFrame(some_data)
         >>> 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 at 5th and 95th percentile by using clip.
+
+        >>> x = np.random.normal(size=(1000,3))
+        >>> 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")