133
133
"klass" : "Series/DataFrame" ,
134
134
"axes_single_arg" : "int or labels for object" ,
135
135
"args_transpose" : "axes to permute (int or label for object)" ,
136
+ "inplace" : """
137
+ inplace : boolean, default False
138
+ If True, performs operation inplace and returns None.""" ,
136
139
"optional_by" : """
137
140
by : str or list of str
138
141
Name or list of names to sort by""" ,
142
+ "replace_iloc" : """
143
+ This differs from updating with ``.loc`` or ``.iloc``, which require
144
+ you to specify a location to update with some value.""" ,
139
145
}
140
146
141
147
@@ -6475,7 +6481,12 @@ def bfill(
6475
6481
6476
6482
backfill = bfill
6477
6483
6478
- @doc (klass = _shared_doc_kwargs ["klass" ])
6484
+ @doc (
6485
+ _shared_docs ["replace" ],
6486
+ klass = _shared_doc_kwargs ["klass" ],
6487
+ inplace = _shared_doc_kwargs ["inplace" ],
6488
+ replace_iloc = _shared_doc_kwargs ["replace_iloc" ],
6489
+ )
6479
6490
def replace (
6480
6491
self ,
6481
6492
to_replace = None ,
@@ -6485,282 +6496,6 @@ def replace(
6485
6496
regex = False ,
6486
6497
method = "pad" ,
6487
6498
):
6488
- """
6489
- Replace values given in `to_replace` with `value`.
6490
-
6491
- Values of the {klass} are replaced with other values dynamically.
6492
- This differs from updating with ``.loc`` or ``.iloc``, which require
6493
- you to specify a location to update with some value.
6494
-
6495
- Parameters
6496
- ----------
6497
- to_replace : str, regex, list, dict, Series, int, float, or None
6498
- How to find the values that will be replaced.
6499
-
6500
- * numeric, str or regex:
6501
-
6502
- - numeric: numeric values equal to `to_replace` will be
6503
- replaced with `value`
6504
- - str: string exactly matching `to_replace` will be replaced
6505
- with `value`
6506
- - regex: regexs matching `to_replace` will be replaced with
6507
- `value`
6508
-
6509
- * list of str, regex, or numeric:
6510
-
6511
- - First, if `to_replace` and `value` are both lists, they
6512
- **must** be the same length.
6513
- - Second, if ``regex=True`` then all of the strings in **both**
6514
- lists will be interpreted as regexs otherwise they will match
6515
- directly. This doesn't matter much for `value` since there
6516
- are only a few possible substitution regexes you can use.
6517
- - str, regex and numeric rules apply as above.
6518
-
6519
- * dict:
6520
-
6521
- - Dicts can be used to specify different replacement values
6522
- for different existing values. For example,
6523
- ``{{'a': 'b', 'y': 'z'}}`` replaces the value 'a' with 'b' and
6524
- 'y' with 'z'. To use a dict in this way the `value`
6525
- parameter should be `None`.
6526
- - For a DataFrame a dict can specify that different values
6527
- should be replaced in different columns. For example,
6528
- ``{{'a': 1, 'b': 'z'}}`` looks for the value 1 in column 'a'
6529
- and the value 'z' in column 'b' and replaces these values
6530
- with whatever is specified in `value`. The `value` parameter
6531
- should not be ``None`` in this case. You can treat this as a
6532
- special case of passing two lists except that you are
6533
- specifying the column to search in.
6534
- - For a DataFrame nested dictionaries, e.g.,
6535
- ``{{'a': {{'b': np.nan}}}}``, are read as follows: look in column
6536
- 'a' for the value 'b' and replace it with NaN. The `value`
6537
- parameter should be ``None`` to use a nested dict in this
6538
- way. You can nest regular expressions as well. Note that
6539
- column names (the top-level dictionary keys in a nested
6540
- dictionary) **cannot** be regular expressions.
6541
-
6542
- * None:
6543
-
6544
- - This means that the `regex` argument must be a string,
6545
- compiled regular expression, or list, dict, ndarray or
6546
- Series of such elements. If `value` is also ``None`` then
6547
- this **must** be a nested dictionary or Series.
6548
-
6549
- See the examples section for examples of each of these.
6550
- value : scalar, dict, list, str, regex, default None
6551
- Value to replace any values matching `to_replace` with.
6552
- For a DataFrame a dict of values can be used to specify which
6553
- value to use for each column (columns not in the dict will not be
6554
- filled). Regular expressions, strings and lists or dicts of such
6555
- objects are also allowed.
6556
- inplace : bool, default False
6557
- If True, in place. Note: this will modify any
6558
- other views on this object (e.g. a column from a DataFrame).
6559
- Returns the caller if this is True.
6560
- limit : int or None, default None
6561
- Maximum size gap to forward or backward fill.
6562
- regex : bool or same types as `to_replace`, default False
6563
- Whether to interpret `to_replace` and/or `value` as regular
6564
- expressions. If this is ``True`` then `to_replace` *must* be a
6565
- string. Alternatively, this could be a regular expression or a
6566
- list, dict, or array of regular expressions in which case
6567
- `to_replace` must be ``None``.
6568
- method : {{'pad', 'ffill', 'bfill', `None`}}
6569
- The method to use when for replacement, when `to_replace` is a
6570
- scalar, list or tuple and `value` is ``None``.
6571
-
6572
- Returns
6573
- -------
6574
- {klass} or None
6575
- Object after replacement or None if ``inplace=True``.
6576
-
6577
- Raises
6578
- ------
6579
- AssertionError
6580
- * If `regex` is not a ``bool`` and `to_replace` is not
6581
- ``None``.
6582
-
6583
- TypeError
6584
- * If `to_replace` is not a scalar, array-like, ``dict``, or ``None``
6585
- * If `to_replace` is a ``dict`` and `value` is not a ``list``,
6586
- ``dict``, ``ndarray``, or ``Series``
6587
- * If `to_replace` is ``None`` and `regex` is not compilable
6588
- into a regular expression or is a list, dict, ndarray, or
6589
- Series.
6590
- * When replacing multiple ``bool`` or ``datetime64`` objects and
6591
- the arguments to `to_replace` does not match the type of the
6592
- value being replaced
6593
-
6594
- ValueError
6595
- * If a ``list`` or an ``ndarray`` is passed to `to_replace` and
6596
- `value` but they are not the same length.
6597
-
6598
- See Also
6599
- --------
6600
- {klass}.fillna : Fill NA values.
6601
- {klass}.where : Replace values based on boolean condition.
6602
- Series.str.replace : Simple string replacement.
6603
-
6604
- Notes
6605
- -----
6606
- * Regex substitution is performed under the hood with ``re.sub``. The
6607
- rules for substitution for ``re.sub`` are the same.
6608
- * Regular expressions will only substitute on strings, meaning you
6609
- cannot provide, for example, a regular expression matching floating
6610
- point numbers and expect the columns in your frame that have a
6611
- numeric dtype to be matched. However, if those floating point
6612
- numbers *are* strings, then you can do this.
6613
- * This method has *a lot* of options. You are encouraged to experiment
6614
- and play with this method to gain intuition about how it works.
6615
- * When dict is used as the `to_replace` value, it is like
6616
- key(s) in the dict are the to_replace part and
6617
- value(s) in the dict are the value parameter.
6618
-
6619
- Examples
6620
- --------
6621
-
6622
- **Scalar `to_replace` and `value`**
6623
-
6624
- >>> s = pd.Series([0, 1, 2, 3, 4])
6625
- >>> s.replace(0, 5)
6626
- 0 5
6627
- 1 1
6628
- 2 2
6629
- 3 3
6630
- 4 4
6631
- dtype: int64
6632
-
6633
- >>> df = pd.DataFrame({{'A': [0, 1, 2, 3, 4],
6634
- ... 'B': [5, 6, 7, 8, 9],
6635
- ... 'C': ['a', 'b', 'c', 'd', 'e']}})
6636
- >>> df.replace(0, 5)
6637
- A B C
6638
- 0 5 5 a
6639
- 1 1 6 b
6640
- 2 2 7 c
6641
- 3 3 8 d
6642
- 4 4 9 e
6643
-
6644
- **List-like `to_replace`**
6645
-
6646
- >>> df.replace([0, 1, 2, 3], 4)
6647
- A B C
6648
- 0 4 5 a
6649
- 1 4 6 b
6650
- 2 4 7 c
6651
- 3 4 8 d
6652
- 4 4 9 e
6653
-
6654
- >>> df.replace([0, 1, 2, 3], [4, 3, 2, 1])
6655
- A B C
6656
- 0 4 5 a
6657
- 1 3 6 b
6658
- 2 2 7 c
6659
- 3 1 8 d
6660
- 4 4 9 e
6661
-
6662
- >>> s.replace([1, 2], method='bfill')
6663
- 0 0
6664
- 1 3
6665
- 2 3
6666
- 3 3
6667
- 4 4
6668
- dtype: int64
6669
-
6670
- **dict-like `to_replace`**
6671
-
6672
- >>> df.replace({{0: 10, 1: 100}})
6673
- A B C
6674
- 0 10 5 a
6675
- 1 100 6 b
6676
- 2 2 7 c
6677
- 3 3 8 d
6678
- 4 4 9 e
6679
-
6680
- >>> df.replace({{'A': 0, 'B': 5}}, 100)
6681
- A B C
6682
- 0 100 100 a
6683
- 1 1 6 b
6684
- 2 2 7 c
6685
- 3 3 8 d
6686
- 4 4 9 e
6687
-
6688
- >>> df.replace({{'A': {{0: 100, 4: 400}}}})
6689
- A B C
6690
- 0 100 5 a
6691
- 1 1 6 b
6692
- 2 2 7 c
6693
- 3 3 8 d
6694
- 4 400 9 e
6695
-
6696
- **Regular expression `to_replace`**
6697
-
6698
- >>> df = pd.DataFrame({{'A': ['bat', 'foo', 'bait'],
6699
- ... 'B': ['abc', 'bar', 'xyz']}})
6700
- >>> df.replace(to_replace=r'^ba.$', value='new', regex=True)
6701
- A B
6702
- 0 new abc
6703
- 1 foo new
6704
- 2 bait xyz
6705
-
6706
- >>> df.replace({{'A': r'^ba.$'}}, {{'A': 'new'}}, regex=True)
6707
- A B
6708
- 0 new abc
6709
- 1 foo bar
6710
- 2 bait xyz
6711
-
6712
- >>> df.replace(regex=r'^ba.$', value='new')
6713
- A B
6714
- 0 new abc
6715
- 1 foo new
6716
- 2 bait xyz
6717
-
6718
- >>> df.replace(regex={{r'^ba.$': 'new', 'foo': 'xyz'}})
6719
- A B
6720
- 0 new abc
6721
- 1 xyz new
6722
- 2 bait xyz
6723
-
6724
- >>> df.replace(regex=[r'^ba.$', 'foo'], value='new')
6725
- A B
6726
- 0 new abc
6727
- 1 new new
6728
- 2 bait xyz
6729
-
6730
- Compare the behavior of ``s.replace({{'a': None}})`` and
6731
- ``s.replace('a', None)`` to understand the peculiarities
6732
- of the `to_replace` parameter:
6733
-
6734
- >>> s = pd.Series([10, 'a', 'a', 'b', 'a'])
6735
-
6736
- When one uses a dict as the `to_replace` value, it is like the
6737
- value(s) in the dict are equal to the `value` parameter.
6738
- ``s.replace({{'a': None}})`` is equivalent to
6739
- ``s.replace(to_replace={{'a': None}}, value=None, method=None)``:
6740
-
6741
- >>> s.replace({{'a': None}})
6742
- 0 10
6743
- 1 None
6744
- 2 None
6745
- 3 b
6746
- 4 None
6747
- dtype: object
6748
-
6749
- When ``value=None`` and `to_replace` is a scalar, list or
6750
- tuple, `replace` uses the method parameter (default 'pad') to do the
6751
- replacement. So this is why the 'a' values are being replaced by 10
6752
- in rows 1 and 2 and 'b' in row 4 in this case.
6753
- The command ``s.replace('a', None)`` is actually equivalent to
6754
- ``s.replace(to_replace='a', value=None, method='pad')``:
6755
-
6756
- >>> s.replace('a', None)
6757
- 0 10
6758
- 1 10
6759
- 2 10
6760
- 3 b
6761
- 4 b
6762
- dtype: object
6763
- """
6764
6499
if not (
6765
6500
is_scalar (to_replace )
6766
6501
or is_re_compilable (to_replace )
0 commit comments