pandas.DataFrame.replace

DataFrame.replace(to_replace=None, value=<no_default>, *, inplace=False, limit=None, regex=False, method=<no_default>)[source]

Заменяет значения, указанные в to_replace, на value.

Значения Series/DataFrame динамически заменяются другими значениями. Это отличается от обновления с помощью .loc или .iloc, для которого необходимо указать место, где нужно обновить значение.

Параметры:

to_replace:str, regex, list, dict, Series, int, float, or None

Способ поиска значений, которые будут заменены.

• числовое значение, str или регулярное выражение:

  • числовое значение: числовые значения, равные to_replace, будут заменены на value

  • str: строки, точно совпадающие с to_replace, будут заменены на value

  • регулярное выражение: строки, соответствующие регулярным выражениям to_replace, будут заменены на value

• список str, регулярных выражений или числовых значений:

  • Во-первых, если to_replace и value — это списки, они должны иметь одинаковую длину.

  • Во-вторых, если regex=True, все строки в обоих списках будут интерпретироваться как регулярные выражения, иначе они будут сопоставляться напрямую. Для value это не имеет большого значения, поскольку можно использовать лишь несколько вариантов регулярных выражений для подстановки.

  • К строкам str, регулярным выражениям и числовым значениям применяются описанные выше правила.

• dict:

  • С помощью dict можно задать разные значения замены для разных существующих значений. Например, {'a': 'b', 'y': 'z'} заменяет значение ‘a’ на ‘b’, а ‘y’ на ‘z’. Чтобы использовать dict таким образом, не следует задавать необязательный параметр value.

  • Для DataFrame с помощью dict можно указать, что в разных столбцах следует заменять разные значения. Например, {'a': 1, 'b': 'z'} ищет значение 1 в столбце ‘a’ и значение ‘z’ в столбце ‘b’ и заменяет эти значения на то, что указано в value. В этом случае параметр value не следует None. Это можно рассматривать как особый случай передачи двух списков, за исключением того, что здесь указывается столбец для поиска.

  • Для DataFrame вложенные словари, например {'a': {'b': np.nan}}, интерпретируются следующим образом: в столбце ‘a’ ищется значение ‘b’, и оно заменяется на NaN. Чтобы использовать вложенный словарь таким образом, необязательный параметр value задавать не следует. Также можно вкладывать регулярные выражения. Обратите внимание, что имена столбцов (ключи верхнего уровня во вложенном словаре) не могут быть регулярными выражениями.

• None:

  • Это означает, что аргумент regex должен быть строкой, скомпилированным регулярным выражением или списком, dict, ndarray либо Series из таких элементов. Если value также None, это должен быть вложенный словарь или Series.

Примеры каждого из этих вариантов приведены в разделе примеров.

value:scalar, dict, list, str, regex, default None

Значение, на которое заменяются все значения, соответствующие to_replace. Для DataFrame можно использовать dict значений, чтобы указать, какое значение использовать для каждого столбца (столбцы, отсутствующие в dict, заполняться не будут). Также допускаются регулярные выражения, строки и списки или dict таких объектов.

inplace:bool, default False

Если True, операция выполняется на месте и возвращает None.

limit:int, default None

Максимальный размер промежутка для заполнения вперёд или назад.

Устарело с версии 2.1.0.

regex:bool or same types as to_replace, default False

Следует ли интерпретировать to_replace и/или value как регулярные выражения. В качестве альтернативы здесь можно передать регулярное выражение либо список, dict или массив регулярных выражений; в этом случае to_replace должен быть None.

method:{‘pad’, ‘ffill’, ‘bfill’}

Метод замены, используемый, когда to_replace — скалярное значение, список или кортеж, а value — None.

Устарело с версии 2.1.0.

Возвращает:

Series/DataFrame

Объект после замены.

Исключения:

AssertionError

• Если regex не является bool, а to_replace не является None.

TypeError

• Если to_replace не является скалярным значением, объектом, подобным массиву, dict или None

• Если to_replace — это dict, а value не является list, dict, ndarray или Series

• Если to_replace — это None, а regex нельзя скомпилировать в регулярное выражение либо он является списком, dict, ndarray или Series.

• При замене нескольких объектов bool или datetime64, если аргументы to_replace не соответствуют типу заменяемого значения

ValueError

• Если в to_replace и value передан list или ndarray, но их длины не совпадают.

См. также

Series.fillna

Заполнить значения NA.

DataFrame.fillna

Заполнить значения NA.

Series.where

Заменить значения на основе логического условия.

DataFrame.where

Заменить значения на основе логического условия.

DataFrame.map

Применить функцию к каждому элементу DataFrame.

Series.map

Сопоставить значения Series согласно входному отображению или функции.

Series.str.replace

Простая замена строк.

Примечания

• Подстановка с использованием регулярных выражений выполняется под капотом с помощью re.sub. Правила подстановки для re.sub такие же.

• Регулярные выражения выполняют замену только в строках. Это значит, что нельзя, например, передать регулярное выражение для поиска чисел с плавающей точкой и ожидать, что оно найдёт значения в столбцах DataFrame с числовым типом данных. Однако если эти числа с плавающей точкой представлены строками, то это сработает.

• У этого метода очень много параметров. Рекомендуется экспериментировать с ним, чтобы лучше понять принцип его работы.

• Если в качестве значения to_replace используется dict, то его ключи соответствуют части to_replace, а значения — параметру value.

Примеры

Скалярные значения `to_replace` и `value`

>>> s = pd.Series([1, 2, 3, 4, 5])
>>> s.replace(1, 5)
0    5
1    2
2    3
3    4
4    5
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

Спископодобный `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    3
1    3
2    3
3    4
4    5
dtype: int64

Словареподобный `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

Регулярное выражение `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

Сравните поведение s.replace({'a': None}) и s.replace('a', None), чтобы понять особенности параметра to_replace:

>>> s = pd.Series([10, 'a', 'a', 'b', 'a'])

При использовании dict в качестве значения to_replace его значения соответствуют параметру value. s.replace({'a': None}) эквивалентно 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

Если value не передан явно, а to_replace — скалярное значение, список или кортеж, replace использует для замены параметр method (по умолчанию ‘pad’). Поэтому в данном случае значения ‘a’ заменяются на 10 в строках 1 и 2, а значение ‘b’ — в строке 4.

>>> s.replace('a')
0    10
1    10
2    10
3     b
4     b
dtype: object

Устарело с версии 2.1.0: Параметр ‘method’ и поведение заполнения устарели.

С другой стороны, если None явно передан для value, он будет учтён:

>>> s.replace('a', None)
0      10
1    None
2    None
3       b
4    None
dtype: object

Изменено в версии 1.4.0: Ранее явно заданный None молча игнорировался.

Если regex=True, value не является None, а to_replace — строка, замена будет применена ко всем столбцам DataFrame.

>>> df = pd.DataFrame({'A': [0, 1, 2, 3, 4],
...                    'B': ['a', 'b', 'c', 'd', 'e'],
...                    'C': ['f', 'g', 'h', 'i', 'j']})

>>> df.replace(to_replace='^[a-g]', value='e', regex=True)
    A  B  C
0  0  e  e
1  1  e  e
2  2  e  h
3  3  e  i
4  4  e  j

Если value не является None, а to_replace — словарь, ключи словаря будут соответствовать столбцам DataFrame, к которым будет применена замена.

>>> df.replace(to_replace={'B': '^[a-c]', 'C': '^[h-j]'}, value='e', regex=True)
    A  B  C
0  0  e  f
1  1  e  g
2  2  e  e
3  3  d  e
4  4  e  e