ENH: Add replace method to Index

doc/source/whatsnew/v1.1.0.rst

@@ -341,6 +341,7 @@ Other enhancements
 - :meth:`DataFrame.agg` and :meth:`Series.agg` now accept named aggregation for renaming the output columns/indexes. (:issue:`26513`)
 - ``compute.use_numba`` now exists as a configuration option that utilizes the numba engine when available (:issue:`33966`, :issue:`35374`)
 - :meth:`Series.plot` now supports asymmetric error bars. Previously, if :meth:`Series.plot` received a "2xN" array with error values for `yerr` and/or `xerr`, the left/lower values (first row) were mirrored, while the right/upper values (second row) were ignored. Now, the first row represents the left/lower error values and the second row the right/upper error values. (:issue:`9536`)
+- :class:`Index` and :class:`MultiIndex` now has a `replace()` method (:issue:`19495`).
 
 .. ---------------------------------------------------------------------------
 

pandas/core/frame.py

@@ -141,6 +141,7 @@
 )
 from pandas.core.reshape.melt import melt
 from pandas.core.series import Series
+from pandas.core.shared_docs import _shared_doc_kwargs as core_shared_doc_kwargs
 from pandas.core.sorting import ensure_key_mapped
 
 from pandas.io.common import get_filepath_or_buffer
@@ -4371,7 +4372,12 @@ def pop(self, item: Label) -> Series:
         """
         return super().pop(item=item)
 
-    @doc(NDFrame.replace, **_shared_doc_kwargs)
+    @doc(
+        NDFrame.replace,
+        inplace=core_shared_doc_kwargs["inplace"],
+        replace_iloc=core_shared_doc_kwargs["replace_iloc"],
+        **_shared_doc_kwargs,
+    )
     def replace(
         self,
         to_replace=None,

pandas/core/generic.py

@@ -97,7 +97,7 @@
 from pandas.core.internals import BlockManager
 from pandas.core.missing import find_valid_index
 from pandas.core.ops import _align_method_FRAME
-from pandas.core.shared_docs import _shared_docs
+from pandas.core.shared_docs import _shared_doc_kwargs, _shared_docs
 
 from pandas.io.formats import format as fmt
 from pandas.io.formats.format import DataFrameFormatter, format_percentiles
@@ -109,14 +109,16 @@
 
 # goal is to be able to define the docs close to function, while still being
 # able to share
-_shared_doc_kwargs = dict(
-    axes="keywords for axes",
-    klass="Series/DataFrame",
-    axes_single_arg="int or labels for object",
-    args_transpose="axes to permute (int or label for object)",
-    optional_by="""
-        by : str or list of str
-            Name or list of names to sort by""",
+_shared_doc_kwargs.update(
+    dict(
+        axes="keywords for axes",
+        klass="Series/DataFrame",
+        axes_single_arg="int or labels for object",
+        args_transpose="axes to permute (int or label for object)",
+        optional_by="""
+            by : str or list of str
+                Name or list of names to sort by""",
+    )
 )
 
 
@@ -6130,7 +6132,12 @@ def bfill(
 
     backfill = bfill
 
-    @doc(klass=_shared_doc_kwargs["klass"])
+    @doc(
+        _shared_docs["to_replace"],
+        klass=_shared_doc_kwargs["klass"],
+        inplace=_shared_doc_kwargs["inplace"],
+        replace_iloc=_shared_doc_kwargs["replace_iloc"],
+    )
     def replace(
         self,
         to_replace=None,
@@ -6140,299 +6147,7 @@ def replace(
         regex=False,
         method="pad",
     ):
-        """
-        Replace values given in `to_replace` with `value`.
-
-        Values of the {klass} are replaced with other values dynamically.
-        This differs from updating with ``.loc`` or ``.iloc``, which require
-        you to specify a location to update with some value.
-
-        Parameters
-        ----------
-        to_replace : str, regex, list, dict, Series, int, float, or None
-            How to find the values that will be replaced.
-
-            * 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
-                  `value`
-
-            * list of str, regex, or numeric:
-
-                - First, if `to_replace` and `value` are both lists, they
-                  **must** be the same length.
-                - Second, if ``regex=True`` then all of the strings in **both**
-                  lists will be interpreted as regexs otherwise they will match
-                  directly. This doesn't matter much for `value` since there
-                  are only a few possible substitution regexes you can use.
-                - str, regex and numeric rules apply as above.
-
-            * dict:
-
-                - Dicts can be used to specify different replacement values
-                  for different existing values. For example,
-                  ``{{'a': 'b', 'y': 'z'}}`` replaces the value 'a' with 'b' and
-                  'y' with 'z'. To use a dict in this way the `value`
-                  parameter should be `None`.
-                - For a DataFrame a dict can specify that different values
-                  should be replaced in different columns. For example,
-                  ``{{'a': 1, 'b': 'z'}}`` looks for the value 1 in column 'a'
-                  and the value 'z' in column 'b' and replaces these values
-                  with whatever is specified in `value`. The `value` parameter
-                  should not be ``None`` in this case. You can treat this as a
-                  special case of passing two lists except that you are
-                  specifying the column to search in.
-                - For a DataFrame nested dictionaries, e.g.,
-                  ``{{'a': {{'b': np.nan}}}}``, are read as follows: look in column
-                  'a' for the value 'b' and replace it with NaN. The `value`
-                  parameter should be ``None`` to use a nested dict in this
-                  way. You can nest regular expressions as well. Note that
-                  column names (the top-level dictionary keys in a nested
-                  dictionary) **cannot** be regular expressions.
-
-            * None:
-
-                - This means that the `regex` argument must be a string,
-                  compiled regular expression, or list, dict, ndarray or
-                  Series of such elements. If `value` is also ``None`` then
-                  this **must** be a nested dictionary or Series.
-
-            See the examples section for examples of each of these.
-        value : scalar, dict, list, str, regex, default None
-            Value to replace any values matching `to_replace` with.
-            For a DataFrame a dict of values can be used to specify which
-            value to use for each column (columns not in the dict will not be
-            filled). Regular expressions, strings and lists or dicts of such
-            objects are also allowed.
-        inplace : bool, default False
-            If True, in place. Note: this will modify any
-            other views on this object (e.g. a column from a DataFrame).
-            Returns the caller if this is True.
-        limit : int, default None
-            Maximum size gap to forward or backward fill.
-        regex : bool or same types as `to_replace`, default False
-            Whether to interpret `to_replace` and/or `value` as regular
-            expressions. If this is ``True`` then `to_replace` *must* be a
-            string. Alternatively, this could be a regular expression or a
-            list, dict, or array of regular expressions in which case
-            `to_replace` must be ``None``.
-        method : {{'pad', 'ffill', 'bfill', `None`}}
-            The method to use when for replacement, when `to_replace` is a
-            scalar, list or tuple and `value` is ``None``.
-
-            .. versionchanged:: 0.23.0
-                Added to DataFrame.
-
-        Returns
-        -------
-        {klass}
-            Object after replacement.
-
-        Raises
-        ------
-        AssertionError
-            * If `regex` is not a ``bool`` and `to_replace` is not
-              ``None``.
-
-        TypeError
-            * If `to_replace` is not a scalar, array-like, ``dict``, or ``None``
-            * If `to_replace` is a ``dict`` and `value` is not a ``list``,
-              ``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 arguments to `to_replace` does not match the type of the
-              value being replaced
-
-        ValueError
-            * If a ``list`` or an ``ndarray`` is passed to `to_replace` and
-              `value` but they are not the same length.
-
-        See Also
-        --------
-        {klass}.fillna : Fill NA values.
-        {klass}.where : Replace values based on boolean condition.
-        Series.str.replace : Simple string replacement.
-
-        Notes
-        -----
-        * Regex substitution is performed under the hood with ``re.sub``. The
-          rules for substitution for ``re.sub`` are the same.
-        * Regular expressions will only substitute on strings, meaning you
-          cannot provide, for example, a regular expression matching floating
-          point numbers and expect the columns in your frame that have a
-          numeric dtype to be matched. However, if those floating point
-          numbers *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.
-        * When dict is used as the `to_replace` value, it is like
-          key(s) in the dict are the to_replace part and
-          value(s) in the dict are the value parameter.
-
-        Examples
-        --------
-
-        **Scalar `to_replace` and `value`**
 
-        >>> s = pd.Series([0, 1, 2, 3, 4])
-        >>> s.replace(0, 5)
-        0    5
-        1    1
-        2    2
-        3    3
-        4    4
-        dtype: int64
-
-        >>> 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
-
-        **List-like `to_replace`**
-
-        >>> df.replace([0, 1, 2, 3], 4)
-           A  B  C
-        0  4  5  a
-        1  4  6  b
-        2  4  7  c
-        3  4  8  d
-        4  4  9  e
-
-        >>> df.replace([0, 1, 2, 3], [4, 3, 2, 1])
-           A  B  C
-        0  4  5  a
-        1  3  6  b
-        2  2  7  c
-        3  1  8  d
-        4  4  9  e
-
-        >>> s.replace([1, 2], method='bfill')
-        0    0
-        1    3
-        2    3
-        3    3
-        4    4
-        dtype: int64
-
-        **dict-like `to_replace`**
-
-        >>> 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
-
-        >>> 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
-
-        >>> df.replace({{'A': {{0: 100, 4: 400}}}})
-             A  B  C
-        0  100  5  a
-        1    1  6  b
-        2    2  7  c
-        3    3  8  d
-        4  400  9  e
-
-        **Regular expression `to_replace`**
-
-        >>> df = pd.DataFrame({{'A': ['bat', 'foo', 'bait'],
-        ...                    'B': ['abc', 'bar', 'xyz']}})
-        >>> df.replace(to_replace=r'^ba.$', value='new', regex=True)
-              A    B
-        0   new  abc
-        1   foo  new
-        2  bait  xyz
-
-        >>> df.replace({{'A': r'^ba.$'}}, {{'A': 'new'}}, regex=True)
-              A    B
-        0   new  abc
-        1   foo  bar
-        2  bait  xyz
-
-        >>> df.replace(regex=r'^ba.$', value='new')
-              A    B
-        0   new  abc
-        1   foo  new
-        2  bait  xyz
-
-        >>> df.replace(regex={{r'^ba.$': 'new', 'foo': 'xyz'}})
-              A    B
-        0   new  abc
-        1   xyz  new
-        2  bait  xyz
-
-        >>> df.replace(regex=[r'^ba.$', 'foo'], value='new')
-              A    B
-        0   new  abc
-        1   new  new
-        2  bait  xyz
-
-        Note that when replacing multiple ``bool`` or ``datetime64`` objects,
-        the data types in the `to_replace` parameter must match the data
-        type of the value being replaced:
-
-        >>> df = pd.DataFrame({{'A': [True, False, True],
-        ...                    'B': [False, True, False]}})
-        >>> df.replace({{'a string': 'new value', True: False}})  # raises
-        Traceback (most recent call last):
-            ...
-        TypeError: Cannot compare types 'ndarray(dtype=bool)' and 'str'
-
-        This raises a ``TypeError`` because one of the ``dict`` keys is not of
-        the correct type for replacement.
-
-        Compare the behavior of ``s.replace({{'a': None}})`` and
-        ``s.replace('a', None)`` to understand the peculiarities
-        of the `to_replace` parameter:
-
-        >>> s = pd.Series([10, 'a', 'a', 'b', 'a'])
-
-        When one uses a dict as the `to_replace` value, it is like the
-        value(s) in the dict are equal to the `value` parameter.
-        ``s.replace({{'a': None}})`` is equivalent to
-        ``s.replace(to_replace={{'a': None}}, value=None, method=None)``:
-
-        >>> s.replace({{'a': None}})
-        0      10
-        1    None
-        2    None
-        3       b
-        4    None
-        dtype: object
-
-        When ``value=None`` and `to_replace` is a scalar, list or
-        tuple, `replace` uses the method parameter (default 'pad') to do the
-        replacement. So this is why the 'a' values are being replaced by 10
-        in rows 1 and 2 and 'b' in row 4 in this case.
-        The command ``s.replace('a', None)`` is actually equivalent to
-        ``s.replace(to_replace='a', value=None, method='pad')``:
-
-        >>> s.replace('a', None)
-        0    10
-        1    10
-        2    10
-        3     b
-        4     b
-        dtype: object
-    """
         if not (
             is_scalar(to_replace)
             or is_re_compilable(to_replace)