DOC: update the pandas.DataFrame.clip docstring

pandas/core/generic.py

@@ -5601,53 +5601,83 @@ 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
-            Align object with lower and upper along the given axis.
+        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
+            Apply clip by index (i.e. by rows) or columns.
         inplace : boolean, default False
             Whether to perform the operation in place on the data
-                .. versionadded:: 0.21.0
+                .. versionadded:: 0.21.0.
+        *args : Additional keywords have no effect but might be accepted
+            for compatibility with numpy.
+        **kwargs : Additional keywords have no effect but might be accepted
+            for compatibility with numpy.
 
         Returns
         -------
-        clipped : Series
+        `Series` or `DataFrame`.
+            DataFrame is returned with those values above/below the
+            `upper`/`'lower` thresholds set to the threshold values.
+
+        See Also
+        --------
+        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, index = ['foo', 'bar', 'foobar'])
         >>> 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
+        foo 1   4   7
+        bar 2   5   8
+        foobar  3   6   9001
+
+        >>> df.clip(lower=1, upper=9)
+            a   b   c
+        foo 1   4   7
+        bar 2   5   8
+        foobar  3   6   9
+
+        You can clip each column or row with different thresholds by passing
+        a ``Series`` to the lower/upper argument. Use the axis argument to clip
+        by column or rows.
+
+        >>> col_thresh = pd.Series({'a':4, 'b':5, 'c':6})
+        >>> df.clip(lower=col_thresh, axis='columns')
+            a   b   c
+        foo 4   5   7
+        bar 4   5   8
+        foobar  4   6   9001
+
+        Clip the foo, bar, and foobar rows with lower thresholds 5, 7, and 10.
+
+        >>> row_thresh = pd.Series({'foo': 5, 'bar': 7, 'foobar': 10})
+        >>> df.clip(lower=row_thresh, axis='index')
+            a   b   c
+        foo 5   5   7
+        bar 7   7   8
+        foobar  10  10  9001
+
+        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.
+        `Winsorizing <https://en.wikipedia.org/wiki/Winsorizing>`__ is a
+        related method, whereby the data are clipped at
+        the 5th and 95th percentiles.
+
+        >>> lwr_thresh = df.quantile(0.05)
+        >>> upr_thresh = df.quantile(0.95)
+        >>> dfw = df.clip(lower=lwr_thresh, upper=upr_thresh, axis='columns')
         """
         if isinstance(self, ABCPanel):
             raise NotImplementedError("clip is not supported yet for panels")