pandas 1.4.2
NotesParametersRaisesReturnsBackRef
replace(self, to_replace=None, value=<no_default>, inplace: 'bool' = False, limit=None, regex: 'bool' = False, method: 'str | lib.NoDefault' = <no_default>)

Values of the DataFrame 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.

Notes

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 :None:None:`to_replace` will be replaced with :None:None:`value`

    • str: string exactly matching :None:None:`to_replace` will be replaced with :None:None:`value`

    • regex: regexs matching :None:None:`to_replace` will be replaced with :None:None:`value`

  • list of str, regex, or numeric:

    • First, if :None:None:`to_replace` and :None:None:`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 :None:None:`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 :None:None:`value` parameter should be :None:None:`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 :None:None:`value`. The :None:None:`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 :None:None:`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 :None:None:`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 :None:None:`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, performs operation inplace and returns None.

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 :None:None:`to_replace` and/or :None:None:`value` as regular expressions. If this is True then :None:None:`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 :None:None:`to_replace` must be None .

method : {'pad', 'ffill', 'bfill', `None`}

The method to use when for replacement, when :None:None:`to_replace` is a scalar, list or tuple and :None:None:`value` is None .

versionchanged

Added to DataFrame.

Raises

AssertionError

  • If regex is not a bool and :None:None:`to_replace` is not None .

TypeError

  • If :None:None:`to_replace` is not a scalar, array-like, dict , or None

  • If :None:None:`to_replace` is a dict and :None:None:`value` is not a list , dict , ndarray , or Series

  • If :None:None:`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 :None:None:`to_replace` does not match the type of the value being replaced

ValueError

  • If a list or an ndarray is passed to :None:None:`to_replace` and :None:None:`value` but they are not the same length.

Returns

DataFrame

Object after replacement.

Replace values given in :None:None:`to_replace` with :None:None:`value`.

See Also

DataFrame.fillna

Fill NA values.

DataFrame.where

Replace values based on boolean condition.

Series.str.replace

Simple string replacement.

Examples

Scalar `to_replace` and `value`

This example is valid syntax, but we were not able to check execution
>>> s = pd.Series([1, 2, 3, 4, 5])
... s.replace(1, 5)
0    5
1    2
2    3
3    4
4    5
dtype: int64
This example is valid syntax, but we were not able to check execution
>>> 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`

This example is valid syntax, but we were not able to check execution
>>> 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
This example is valid syntax, but we were not able to check execution
>>> 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
This example is valid syntax, but we were not able to check execution
>>> s.replace([1, 2], method='bfill')
0    3
1    3
2    3
3    4
4    5
dtype: int64

dict-like `to_replace`

This example is valid syntax, but we were not able to check execution
>>> 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
This example is valid syntax, but we were not able to check execution
>>> 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
This example is valid syntax, but we were not able to check execution
>>> 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`

This example is valid syntax, but we were not able to check execution
>>> 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
This example is valid syntax, but we were not able to check execution
>>> df.replace({'A': r'^ba.$'}, {'A': 'new'}, regex=True)
        A    B
0   new  abc
1   foo  bar
2  bait  xyz
This example is valid syntax, but we were not able to check execution
>>> df.replace(regex=r'^ba.$', value='new')
        A    B
0   new  abc
1   foo  new
2  bait  xyz
This example is valid syntax, but we were not able to check execution
>>> df.replace(regex={r'^ba.$': 'new', 'foo': 'xyz'})
        A    B
0   new  abc
1   xyz  new
2  bait  xyz
This example is valid syntax, but we were not able to check execution
>>> df.replace(regex=[r'^ba.$', 'foo'], value='new')
        A    B
0   new  abc
1   new  new
2  bait  xyz

Compare the behavior of s.replace({'a': None}) and s.replace('a', None) to understand the peculiarities of the :None:None:`to_replace` parameter:

This example is valid syntax, but we were not able to check execution
>>> s = pd.Series([10, 'a', 'a', 'b', 'a'])

When one uses a dict as the :None:None:`to_replace` value, it is like the value(s) in the dict are equal to the :None:None:`value` parameter. s.replace({'a': None}) is equivalent to s.replace(to_replace={'a': None}, value=None, method=None) :

This example is valid syntax, but we were not able to check execution
>>> s.replace({'a': None})
0      10
1    None
2    None
3       b
4    None
dtype: object

When value is not explicitly passed and :None:None:`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.

This example is valid syntax, but we were not able to check execution
>>> s.replace('a')
0    10
1    10
2    10
3     b
4     b
dtype: object

On the other hand, if None is explicitly passed for value , it will be respected:

This example is valid syntax, but we were not able to check execution
>>> s.replace('a', None)
0      10
1    None
2    None
3       b
4    None
dtype: object
versionchanged

Previously the explicit None was silently ignored.

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

pandas.core.frame.DataFrame.replace

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

File: /pandas/core/frame.py#5272
type: <class 'function'>
Commit: