pandas.Series.replace

Series.replace(to_replace=None, value=<no_default>, *, inplace=False, limit=None, regex=False, method=<no_default>)[исходный код]

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

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

Параметры:

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

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

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

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

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

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

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

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

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

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

• словарь:

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

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

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

• None:

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

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

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

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

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 как регулярные выражения. Вместо этого здесь может быть регулярное выражение либо список, словарь или массив регулярных выражений; в таком случае 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 не является скаляром, объектом типа array-like, dict или None

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

• Если to_replace — None, а regex нельзя скомпилировать в регулярное выражение либо он является списком, словарём, 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 с числовым dtype. Однако если эти числа с плавающей точкой представлены строками, это возможно.

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

• Если в качестве значения to_replace используется словарь, его ключи соответствуют части 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'])

При использовании словаря в качестве значения 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’ и поведение заполнения устарели.

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

>>> 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