DOC: Improve replace docstring (pandas-dev#17673)

Author: reidy-p

pandas/core/generic.py

@@ -4362,8 +4362,9 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
         ----------
         to_replace : str, regex, list, dict, Series, numeric, or None
 
-            * str or regex:
-
+            * numeric, str or regex: 
+                - numeric: numeric values equal to `to_replace` will be 
+                  replaced with `value`
                 - str: string exactly matching `to_replace` will be replaced
                   with `value`
                 - regex: regexs matching `to_replace` will be replaced with
@@ -4381,14 +4382,16 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
 
             * dict:
 
+                - Keys map to column names and values map to substitution
+                  values. For example, {'a': 1, 'b': 'z'} looks for the value 1
+                  in column 'a' and the value 'z' in column 'b'. You can treat 
+                  this as a special case of passing two lists except that you 
+                  are specifying the column to search in.
                 - Nested dictionaries, e.g., {'a': {'b': nan}}, are read as
                   follows: look in column 'a' for the value 'b' and replace it
-                  with nan. You can nest regular expressions as well. Note that
+                  with NaN. You can nest regular expressions as well. Note that
                   column names (the top-level dictionary keys in a nested
                   dictionary) **cannot** be regular expressions.
-                - Keys map to column names and values map to substitution
-                  values. You can treat this as a special case of passing two
-                  lists except that you are specifying the column to search in.
 
             * None:
 
@@ -4421,13 +4424,12 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
 
         See Also
         --------
-        NDFrame.reindex
-        NDFrame.asfreq
-        NDFrame.fillna
+        :func:`DataFrame.fillna` : Fill NA/NaN values
+        :func:`DataFrame.where` : Replace values based on boolean condition
 
         Returns
         -------
-        filled : NDFrame
+        filled : DataFrame
 
         Raises
         ------
@@ -4438,6 +4440,9 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
               ``dict``, ``ndarray``, or ``Series``
             * If `to_replace` is ``None`` and `regex` is not compilable into a
               regular expression or is a list, dict, ndarray, or Series.
+            * When replacing multiple `bool` or `datetime64` objects and the 
+              the arguments to `to_replace` does not match the type of the 
+              value being replaced
         ValueError
             * If `to_replace` and `value` are ``list`` s or ``ndarray`` s, but
               they are not the same length.
@@ -4453,6 +4458,63 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None,
           *are* strings, then you can do this.
         * This method has *a lot* of options. You are encouraged to experiment
           and play with this method to gain intuition about how it works.
+          
+        Examples
+        --------
+        Simple Cases
+        
+        Scalar Value
+        
+        >>> df = pd.DataFrame({'A': [0, 1, 2, 3, 4],
+        ...                    'B': [5, 6, 7, 8, 9],
+        ...                    'C': ['a', 'b', 'c', 'd', 'e']})
+        >>> df.replace(0, 5)
+           A  B  C
+        0  5  5  a
+        1  1  6  b
+        2  2  7  c
+        3  3  8  d
+        4  4  9  e
+        
+        Lists
+        
+        >>> df.replace([0, 1, 2, 3, 4], [4, 3, 2, 1, 0])
+           A  B  C
+        0  4  5  a
+        1  3  6  b
+        2  2  7  c
+        3  1  8  d
+        4  0  9  e
+        
+        Simple Dict 
+        
+        >>> df.replace({0: 10, 1: 100})
+             A  B  C
+        0   10  5  a
+        1  100  6  b
+        2    2  7  c
+        3    3  8  d
+        4    4  9  e
+        
+        Dict for values by column 
+        
+        >>> df.replace({'A': 0, 'B': 5}, 100)
+             A    B  C
+        0  100  100  a
+        1    1    6  b
+        2    2    7  c
+        3    3    8  d
+        4    4    9  e        
+
+        regex 
+        
+        >>> df = {'a': list(range(4)), 'b': list('ab..'), 'c': ['a', 'b', np.nan, 'd']}
+        >>> df.replace(r'\s*\.\s*', np.nan, regex=True)
+           a    b    c
+        0  0    a    a
+        1  1    b    b
+        2  2  NaN  NaN
+        3  3  NaN    d
 
         """
         inplace = validate_bool_kwarg(inplace, 'inplace')