Skip to content

Commit e05597f

Browse files
committed
use _shared_docs
1 parent 8ab24cd commit e05597f

File tree

3 files changed

+229
-399
lines changed

3 files changed

+229
-399
lines changed

pandas/core/frame.py

+1-212
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@
2020
import warnings
2121
from textwrap import dedent
2222

23-
import pandas as pd
2423
import numpy as np
2524
import numpy.ma as ma
2625

@@ -43,7 +42,6 @@
4342
is_datetimetz,
4443
is_datetime64_any_dtype,
4544
is_datetime64tz_dtype,
46-
is_bool,
4745
is_bool_dtype,
4846
is_integer_dtype,
4947
is_float_dtype,
@@ -3065,218 +3063,9 @@ def fillna(self, value=None, method=None, axis=None, inplace=False,
30653063
inplace=inplace, limit=limit,
30663064
downcast=downcast, **kwargs)
30673065

3066+
@Appender(_shared_docs['replace'] % _shared_doc_kwargs)
30683067
def replace(self, to_replace=None, value=None, inplace=False, limit=None,
30693068
regex=False, method='pad', axis=None):
3070-
"""
3071-
Replace values given in 'to_replace' with 'value'.
3072-
3073-
Parameters
3074-
----------
3075-
to_replace : str, regex, list, dict, Series, numeric, or None
3076-
3077-
* numeric, str or regex:
3078-
3079-
- numeric: numeric values equal to ``to_replace`` will be
3080-
replaced with ``value``
3081-
- str: string exactly matching `to_replace` will be replaced
3082-
with ``value``
3083-
- regex: regexs matching ``to_replace`` will be replaced with
3084-
``value``
3085-
3086-
* list of str, regex, or numeric:
3087-
3088-
- First, if ``to_replace`` and ``value`` are both lists, they
3089-
**must** be the same length.
3090-
- Second, if ``regex=True`` then all of the strings in **both**
3091-
lists will be interpreted as regexs otherwise they will match
3092-
directly. This doesn't matter much for ``value`` since there
3093-
are only a few possible substitution regexes you can use.
3094-
- str and regex rules apply as above.
3095-
3096-
* dict:
3097-
3098-
- Dicts can be used to specify different replacement values
3099-
for different existing values. For example,
3100-
{'a': 'b', 'y': 'z'} replaces the value 'a' with 'b' and
3101-
'y' with 'z'. To use a dict in this way the ``value``
3102-
parameter should be ``None``.
3103-
- Alternatively, a dict can specify that different values
3104-
should be replaced in different columns. For example,
3105-
{'a': 1, 'b': 'z'} looks for the value 1 in column 'a' and
3106-
the value 'z' in column 'b' and replaces these values with
3107-
whatever is specified in ``value``. The ``value`` parameter
3108-
should not be ``None`` in this case. You can treat this as a
3109-
special case of passing two lists except that you are
3110-
specifying the column to search in.
3111-
- Nested dictionaries, e.g., {'a': {'b': np.nan}}, are read as
3112-
follows: look in column 'a' for the value 'b' and replace it
3113-
with NaN. The ``value`` parameter should be ``None`` to use
3114-
a nested dict in this way. You can nest regular expressions
3115-
as well. Note that column names (the top-level dictionary
3116-
keys in a nested dictionary) **cannot** be regular
3117-
expressions.
3118-
3119-
* None:
3120-
3121-
- This means that the ``regex`` argument must be a string,
3122-
compiled regular expression, or list, dict, ndarray or Series
3123-
of such elements. If ``value`` is also ``None`` then this
3124-
**must** be a nested dictionary or ``Series``.
3125-
3126-
See the examples section for examples of each of these.
3127-
value : scalar, dict, list, str, regex, default None
3128-
Value to replace any values matching ``to_replace`` with.
3129-
Alternatively, a dict of values specifying which value to use for
3130-
each column (columns not in the dict will not be filled). Regular
3131-
expressions, strings and lists or dicts of such objects are also
3132-
allowed.
3133-
inplace : boolean, default False
3134-
If True, in place. Note: this will modify any
3135-
other views on this object (e.g. a column from a DataFrame).
3136-
Returns the caller if this is True.
3137-
limit : int, default None
3138-
Maximum size gap to forward or backward fill
3139-
regex : bool or same types as `to_replace`, default False
3140-
Whether to interpret ``to_replace`` and/or ``value`` as regular
3141-
expressions. If this is ``True`` then ``to_replace`` *must* be a
3142-
string. Alternatively, this could be a regular expression or a
3143-
list, dict, or array of regular expressions in which case
3144-
``to_replace`` must be ``None``.
3145-
method : string, optional, {'pad', 'ffill', 'bfill'}
3146-
The method to use when for replacement, when ``to_replace`` is a
3147-
``list``.
3148-
3149-
See Also
3150-
--------
3151-
DataFrame.fillna : Fill NA/NaN values
3152-
DataFrame.where : Replace values based on boolean condition
3153-
3154-
Returns
3155-
-------
3156-
filled : DataFrame
3157-
3158-
Raises
3159-
------
3160-
AssertionError
3161-
* If ``regex`` is not a ``bool`` and ``to_replace`` is not
3162-
``None``.
3163-
TypeError
3164-
* If ``to_replace`` is a ``dict`` and `value` is not a ``list``,
3165-
``dict``, ``ndarray``, or ``Series``
3166-
* If ``to_replace`` is ``None`` and ``regex`` is not compilable
3167-
into a regular expression or is a list, dict, ndarray, or
3168-
Series.
3169-
* When replacing multiple ``bool`` or ``datetime64`` objects and
3170-
the arguments to `to_replace` does not match the type of the
3171-
value being replaced
3172-
ValueError
3173-
* If a ``list`` or an ``ndarray`` is passed to `to_replace` and
3174-
`value` but they are not the same length.
3175-
3176-
Notes
3177-
-----
3178-
* Regex substitution is performed under the hood with ``re.sub``. The
3179-
rules for substitution for ``re.sub`` are the same.
3180-
* Regular expressions will only substitute on strings, meaning you
3181-
cannot provide, for example, a regular expression matching floating
3182-
point numbers and expect the columns in your frame that have a
3183-
numeric dtype to be matched. However, if those floating point
3184-
numbers *are* strings, then you can do this.
3185-
* This method has *a lot* of options. You are encouraged to experiment
3186-
and play with this method to gain intuition about how it works.
3187-
3188-
Examples
3189-
--------
3190-
3191-
>>> df = pd.DataFrame({'A': [0, 1, 2, 3, 4],
3192-
... 'B': [5, 6, 7, 8, 9],
3193-
... 'C': ['a', 'b', 'c', 'd', 'e']})
3194-
>>> df.replace(0, 5)
3195-
A B C
3196-
0 5 5 a
3197-
1 1 6 b
3198-
2 2 7 c
3199-
3 3 8 d
3200-
4 4 9 e
3201-
3202-
>>> df.replace([0, 1, 2, 3], 4)
3203-
A B C
3204-
0 4 5 a
3205-
1 4 6 b
3206-
2 4 7 c
3207-
3 4 8 d
3208-
4 4 9 e
3209-
>>> df.replace([0, 1, 2, 3], [4, 3, 2, 1])
3210-
A B C
3211-
0 4 5 a
3212-
1 3 6 b
3213-
2 2 7 c
3214-
3 1 8 d
3215-
4 4 9 e
3216-
3217-
>>> df.replace({0: 10, 1: 100})
3218-
A B C
3219-
0 10 5 a
3220-
1 100 6 b
3221-
2 2 7 c
3222-
3 3 8 d
3223-
4 4 9 e
3224-
>>> df.replace({'A': 0, 'B': 5}, 100)
3225-
A B C
3226-
0 100 100 a
3227-
1 1 6 b
3228-
2 2 7 c
3229-
3 3 8 d
3230-
4 4 9 e
3231-
>>> df.replace({'A': {0: 100, 4: 400}})
3232-
A B C
3233-
0 100 5 a
3234-
1 1 6 b
3235-
2 2 7 c
3236-
3 3 8 d
3237-
4 400 9 e
3238-
3239-
>>> df = pd.DataFrame({'A': ['bat', 'foo', 'bait'],
3240-
... 'B': ['abc', 'bar', 'xyz']})
3241-
>>> df.replace(to_replace=r'^ba.$', value='new', regex=True)
3242-
A B
3243-
0 new abc
3244-
1 foo new
3245-
2 bait xyz
3246-
>>> df.replace({'A': r'^ba.$'}, {'A': 'new'}, regex=True)
3247-
A B
3248-
0 new abc
3249-
1 foo bar
3250-
2 bait xyz
3251-
>>> df.replace(regex=r'^ba.$', value='new')
3252-
A B
3253-
0 new abc
3254-
1 foo new
3255-
2 bait xyz
3256-
>>> df.replace(regex={r'^ba.$':'new', 'foo':'xyz'})
3257-
A B
3258-
0 new abc
3259-
1 xyz new
3260-
2 bait xyz
3261-
>>> df.replace(regex=[r'^ba.$', 'foo'], value='new')
3262-
A B
3263-
0 new abc
3264-
1 new new
3265-
2 bait xyz
3266-
3267-
Note that when replacing multiple ``bool`` or ``datetime64`` objects,
3268-
the data types in the ``to_replace`` parameter must match the data
3269-
type of the value being replaced:
3270-
3271-
>>> df = pd.DataFrame({'A': [True, False, True],
3272-
... 'B': [False, True, False]})
3273-
>>> df.replace({'a string': 'new value', True: False}) # raises
3274-
TypeError: Cannot compare types 'ndarray(dtype=bool)' and 'str'
3275-
3276-
This raises a ``TypeError`` because one of the ``dict`` keys is not of
3277-
the correct type for replacement.
3278-
3279-
"""
32803069
return super(DataFrame, self).replace(to_replace=to_replace,
32813070
value=value, inplace=inplace,
32823071
limit=limit, regex=regex,

0 commit comments

Comments
 (0)