From 068127caf8b5e2979e9d3a33f8d6a71b36b1c95b Mon Sep 17 00:00:00 2001 From: Gjelt Date: Sun, 11 Mar 2018 03:39:01 +0100 Subject: [PATCH 1/8] DOC: changed pandas.DataFrame/Series.replace docstring --- pandas/core/generic.py | 54 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 50 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 397726181d2fb..bc1bbe7c45ec1 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4869,6 +4869,9 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): _shared_docs['replace'] = (""" Replace values given in 'to_replace' with 'value'. + Values of the DataFrame or a Series are being replaced with + other values. + Parameters ---------- to_replace : str, regex, list, dict, Series, numeric, or None @@ -4934,19 +4937,21 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): other views on this object (e.g. a column from a DataFrame). Returns the caller if this is True. limit : int, default None - Maximum size gap to forward or backward fill + Maximum size gap to forward or backward fill. regex : bool or same types as ``to_replace``, default False Whether to interpret ``to_replace`` and/or ``value`` as regular expressions. If this is ``True`` then ``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 ``to_replace`` must be ``None``. - method : string, optional, {'pad', 'ffill', 'bfill'} + method : string, optional, {'pad', 'ffill', 'bfill'}, default is 'pad' The method to use when for replacement, when ``to_replace`` is a scalar, list or tuple and ``value`` is None. + axis : None + Deprecated. - .. versionchanged:: 0.23.0 - Added to DataFrame + .. versionchanged:: 0.23.0 + Added to DataFrame See Also -------- @@ -5092,6 +5097,47 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): This raises a ``TypeError`` because one of the ``dict`` keys is not of the correct type for replacement. + + Compare the behavior of + ``s.replace('a', None)`` and ``s.replace({'a': None})`` to understand + the pecularities of the ``to_replace`` parameter. + ``s.replace('a', None)`` is actually equivalent to + ``s.replace(to_replace='a', value=None, method='pad')``, + because when ``value=None`` and ``to_replace`` is a scalar, list or + tuple, ``replace`` uses the method parameter to do the replacement. + So this is why the 'a' values are being replaced by 30 in rows 3 and 4 + and 'b' in row 6 in this case. However, this behaviour does not occur + when you use a dict as the ``to_replace`` value. In this case, it is + like the value(s) in the dict are equal to the value parameter. + + >>> s = pd.Series([10, 20, 30, 'a', 'a', 'b', 'a']) + >>> print(s) + 0 10 + 1 20 + 2 30 + 3 a + 4 a + 5 b + 6 a + dtype: object + >>> print(s.replace('a', None)) + 0 10 + 1 20 + 2 30 + 3 30 + 4 30 + 5 b + 6 b + dtype: object + >>> print(s.replace({'a': None})) + 0 10 + 1 20 + 2 30 + 3 None + 4 None + 5 b + 6 None + dtype: object """) @Appender(_shared_docs['replace'] % _shared_doc_kwargs) From 44b7de3a5b7541bb2f4fee8a0f4e8f527b4c1b29 Mon Sep 17 00:00:00 2001 From: Gjelt Date: Sun, 11 Mar 2018 04:08:31 +0100 Subject: [PATCH 2/8] DOC: changed pandas.DataFrame/Series.replace docstring --- pandas/core/generic.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index bc1bbe7c45ec1..2301d997679d6 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4870,7 +4870,8 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): Replace values given in 'to_replace' with 'value'. Values of the DataFrame or a Series are being replaced with - other values. + other values. One or several values can be replaced with one + or several values. Parameters ---------- @@ -4960,7 +4961,8 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): Returns ------- - filled : %(klass)s + %(klass)s + Some values have been substituted for new values. Raises ------ From b502d34e16de5dcf1d3be28d4ae890935e6d4071 Mon Sep 17 00:00:00 2001 From: Gjelt Date: Wed, 14 Mar 2018 23:16:15 +0100 Subject: [PATCH 3/8] DOC: pandas.DataFrame.replace - implemented feedback --- pandas/core/generic.py | 101 ++++++++++++++++++++--------------------- 1 file changed, 49 insertions(+), 52 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 2301d997679d6..7d190ba00e2a6 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4870,13 +4870,15 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): Replace values given in 'to_replace' with 'value'. Values of the DataFrame or a Series are being replaced with - other values. One or several values can be replaced with one - or several values. + other values in a dynamic way. Instead of replacing values in a + specific cell (row/column combination), this method allows for more + flexibility with replacements. For instance, values can be replaced + by specifying lists of values and replacements separately or + with a dynamic set of inputs like dicts. Parameters ---------- to_replace : str, regex, list, dict, Series, numeric, or None - * numeric, str or regex: - numeric: numeric values equal to ``to_replace`` will be @@ -4912,8 +4914,8 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 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 ``value`` + {'a': {'b': np.nan}}, are read as follows: look in column + 'a' for the value 'b' and replace it with NaN. The ``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 @@ -4922,9 +4924,9 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): * None: - This means that the ``regex`` argument must be a string, - compiled regular expression, or list, dict, ndarray or Series - of such elements. If ``value`` is also ``None`` then this - **must** be a nested dictionary or ``Series``. + compiled regular expression, or list, dict, ndarray or + Series of such elements. If ``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 @@ -4945,24 +4947,23 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): string. Alternatively, this could be a regular expression or a list, dict, or array of regular expressions in which case ``to_replace`` must be ``None``. - method : string, optional, {'pad', 'ffill', 'bfill'}, default is 'pad' + method : {'pad', 'ffill', 'bfill', `None`} The method to use when for replacement, when ``to_replace`` is a - scalar, list or tuple and ``value`` is None. + scalar, list or tuple and ``value`` is `None`. + .. versionchanged:: 0.23.0 + Added to DataFrame. axis : None Deprecated. - .. versionchanged:: 0.23.0 - Added to DataFrame - See Also -------- - %(klass)s.fillna : Fill NA/NaN values + %(klass)s.fillna : Fill `NaN` values %(klass)s.where : Replace values based on boolean condition Returns ------- %(klass)s - Some values have been substituted for new values. + Object after replacement. Raises ------ @@ -4993,6 +4994,9 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): numbers *are* strings, then you can do this. * This method has *a lot* of options. You are encouraged to experiment and play with this method to gain intuition about how it works. + * When dict is used as the ``to_replace`` value, it is like + key(s) in the dict are the to_replace part and + value(s) in the dict are the value parameter. Examples -------- @@ -5100,45 +5104,38 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): This raises a ``TypeError`` because one of the ``dict`` keys is not of the correct type for replacement. - Compare the behavior of - ``s.replace('a', None)`` and ``s.replace({'a': None})`` to understand - the pecularities of the ``to_replace`` parameter. - ``s.replace('a', None)`` is actually equivalent to - ``s.replace(to_replace='a', value=None, method='pad')``, - because when ``value=None`` and ``to_replace`` is a scalar, list or - tuple, ``replace`` uses the method parameter to do the replacement. - So this is why the 'a' values are being replaced by 30 in rows 3 and 4 - and 'b' in row 6 in this case. However, this behaviour does not occur - when you use a dict as the ``to_replace`` value. In this case, it is - like the value(s) in the dict are equal to the value parameter. - - >>> s = pd.Series([10, 20, 30, 'a', 'a', 'b', 'a']) - >>> print(s) - 0 10 - 1 20 - 2 30 - 3 a - 4 a - 5 b - 6 a - dtype: object - >>> print(s.replace('a', None)) - 0 10 - 1 20 - 2 30 - 3 30 - 4 30 - 5 b - 6 b - dtype: object - >>> print(s.replace({'a': None})) + Compare the behavior of` `s.replace({'a': None})`` and + ``s.replace('a', None)`` to understand the pecularities + of the ``to_replace`` parameter: + + >>> s = pd.Series([10, 'a', 'a', 'b', 'a']) + + When one uses a dict as the ``to_replace`` value, it is like the + value(s) in the dict are equal to the value parameter. + ``s.replace({'a': None})`` is equivalent to + ``s.replace(to_replace={'a': None}, value=None, method=None)``: + + >>> s.replace({'a': None}) 0 10 - 1 20 - 2 30 - 3 None + 1 None + 2 None + 3 b 4 None - 5 b - 6 None + dtype: object + + When ``value=None`` and ``to_replace`` are 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. + The command ``s.replace('a', None)`` is actually equivalent to + ``s.replace(to_replace='a', value=None, method='pad')``: + + >>> s.replace('a', None) + 0 10 + 1 10 + 2 10 + 3 b + 4 b dtype: object """) From 80bc7ca63c46eda0d8a31b7b2be22d7ce8b2baa2 Mon Sep 17 00:00:00 2001 From: Gjelt Date: Wed, 14 Mar 2018 23:18:04 +0100 Subject: [PATCH 4/8] DOC: pandas.DataFrame.replace - int/float instead of numeric --- pandas/core/generic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 7d190ba00e2a6..4fa1b5502a380 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4878,7 +4878,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): Parameters ---------- - to_replace : str, regex, list, dict, Series, numeric, or None + to_replace : str, regex, list, dict, Series, int, float, or None * numeric, str or regex: - numeric: numeric values equal to ``to_replace`` will be From f05d0afc1ffeb057ccf3b50b5c28ae83c3350a20 Mon Sep 17 00:00:00 2001 From: Gjelt Date: Wed, 14 Mar 2018 23:41:50 +0100 Subject: [PATCH 5/8] DOC: pandas.DataFrame.replace - formatting --- pandas/core/generic.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 4fa1b5502a380..b38df4119dae0 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4950,6 +4950,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): method : {'pad', 'ffill', 'bfill', `None`} The method to use when for replacement, when ``to_replace`` is a scalar, list or tuple and ``value`` is `None`. + .. versionchanged:: 0.23.0 Added to DataFrame. axis : None @@ -5104,7 +5105,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): This raises a ``TypeError`` because one of the ``dict`` keys is not of the correct type for replacement. - Compare the behavior of` `s.replace({'a': None})`` and + Compare the behavior of ``s.replace({'a': None})`` and ``s.replace('a', None)`` to understand the pecularities of the ``to_replace`` parameter: @@ -5115,6 +5116,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): ``s.replace({'a': None})`` is equivalent to ``s.replace(to_replace={'a': None}, value=None, method=None)``: + >>> #s.replace(to_replace={'a': None}, value=None, method=None) >>> s.replace({'a': None}) 0 10 1 None @@ -5130,6 +5132,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): The command ``s.replace('a', None)`` is actually equivalent to ``s.replace(to_replace='a', value=None, method='pad')``: + >>> #s.replace(to_replace='a', value=None, method='pad') >>> s.replace('a', None) 0 10 1 10 From 0a081fe8dbda5bf487bde9c3c8c9cfc0144aae0f Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 15 Mar 2018 09:54:18 -0500 Subject: [PATCH 6/8] Updates. Section headers. Consistent quoting. Formatting. Traceback. --- pandas/core/generic.py | 111 ++++++++++++++++++++++++----------------- 1 file changed, 64 insertions(+), 47 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index b38df4119dae0..8e0027d1b1b43 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4867,34 +4867,33 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): limit=limit, downcast=downcast) _shared_docs['replace'] = (""" - Replace values given in 'to_replace' with 'value'. + Replace values given in `to_replace` with `value`. - Values of the DataFrame or a Series are being replaced with - other values in a dynamic way. Instead of replacing values in a - specific cell (row/column combination), this method allows for more - flexibility with replacements. For instance, values can be replaced - by specifying lists of values and replacements separately or - with a dynamic set of inputs like dicts. + Values of the %(klass)s 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. 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 ``to_replace`` will be - replaced with ``value`` - - str: string exactly matching ``to_replace`` will be replaced - with ``value`` - - regex: regexs matching ``to_replace`` will be replaced with - ``value`` + - numeric: numeric values equal to `to_replace` will be + replaced with `value` + - str: string exactly matching `to_replace` will be replaced + with `value` + - regex: regexs matching `to_replace` will be replaced with + `value` * list of str, regex, or numeric: - - First, if ``to_replace`` and ``value`` are both lists, they + - First, if `to_replace` and `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 ``value`` since there + directly. This doesn't matter much for `value` since there are only a few possible substitution regexes you can use. - str, regex and numeric rules apply as above. @@ -4902,20 +4901,20 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): - 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 ``value`` - parameter should be ``None``. + ``{'a': 'b', 'y': 'z'}`` replaces the value 'a' with 'b' and + 'y' with 'z'. To use a dict in this way the `value` + parameter should be `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 ``value``. The ``value`` parameter + ``{'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 `value`. The `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 ``value`` + ``{'a': {'b': np.nan}}``, are read as follows: look in column + 'a' for the value 'b' and replace it with NaN. The `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 @@ -4923,14 +4922,14 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): * None: - - This means that the ``regex`` argument must be a string, + - This means that the `regex` argument must be a string, compiled regular expression, or list, dict, ndarray or - Series of such elements. If ``value`` is also ``None`` then - this **must** be a nested dictionary or ``Series``. + Series of such elements. If `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 ``to_replace`` with. + Value to replace any values matching `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 @@ -4941,15 +4940,15 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): Returns the caller if this is True. 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 ``to_replace`` and/or ``value`` as regular - expressions. If this is ``True`` then ``to_replace`` *must* be a + regex : bool or same types as `to_replace`, default False + Whether to interpret `to_replace` and/or `value` as regular + expressions. If this is ``True`` then `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 - ``to_replace`` must be ``None``. + `to_replace` must be ``None``. method : {'pad', 'ffill', 'bfill', `None`} - The method to use when for replacement, when ``to_replace`` is a - scalar, list or tuple and ``value`` is `None`. + The method to use when for replacement, when `to_replace` is a + scalar, list or tuple and `value` is ``None``. .. versionchanged:: 0.23.0 Added to DataFrame. @@ -4960,6 +4959,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): -------- %(klass)s.fillna : Fill `NaN` values %(klass)s.where : Replace values based on boolean condition + Series.str.replace : Simple string replacement. Returns ------- @@ -4969,19 +4969,19 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): Raises ------ AssertionError - * If ``regex`` is not a ``bool`` and ``to_replace`` is not + * If `regex` is not a ``bool`` and `to_replace` is not ``None``. TypeError - * If ``to_replace`` is a ``dict`` and ``value`` is not a ``list``, + * If `to_replace` is a ``dict`` and `value` is not a ``list``, ``dict``, ``ndarray``, or ``Series`` - * If ``to_replace`` is ``None`` and ``regex`` is not compilable + * If `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 ``to_replace`` does not match the type of the + the arguments to `to_replace` does not match the type of the value being replaced ValueError - * If a ``list`` or an ``ndarray`` is passed to ``to_replace`` and + * If a ``list`` or an ``ndarray`` is passed to `to_replace` and `value` but they are not the same length. Notes @@ -4995,13 +4995,15 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): numbers *are* strings, then you can do this. * This method has *a lot* of options. You are encouraged to experiment and play with this method to gain intuition about how it works. - * When dict is used as the ``to_replace`` value, it is like + * When dict is used as the `to_replace` value, it is like key(s) in the dict are the to_replace part and value(s) in the dict are the value parameter. Examples -------- + **Scalar `to_replace` and `value`** + >>> s = pd.Series([0, 1, 2, 3, 4]) >>> s.replace(0, 5) 0 5 @@ -5010,6 +5012,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 3 3 4 4 dtype: int64 + >>> df = pd.DataFrame({'A': [0, 1, 2, 3, 4], ... 'B': [5, 6, 7, 8, 9], ... 'C': ['a', 'b', 'c', 'd', 'e']}) @@ -5021,6 +5024,8 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 3 3 8 d 4 4 9 e + **List-like `to_replace`** + >>> df.replace([0, 1, 2, 3], 4) A B C 0 4 5 a @@ -5028,6 +5033,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 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 @@ -5035,6 +5041,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 2 2 7 c 3 1 8 d 4 4 9 e + >>> s.replace([1, 2], method='bfill') 0 0 1 3 @@ -5043,6 +5050,8 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 4 4 dtype: int64 + **dict-like `to_replace`** + >>> df.replace({0: 10, 1: 100}) A B C 0 10 5 a @@ -5050,6 +5059,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 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 @@ -5057,6 +5067,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 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 @@ -5065,6 +5076,8 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 3 3 8 d 4 400 9 e + **Regular expression `to_replace`** + >>> df = pd.DataFrame({'A': ['bat', 'foo', 'bait'], ... 'B': ['abc', 'bar', 'xyz']}) >>> df.replace(to_replace=r'^ba.$', value='new', regex=True) @@ -5072,21 +5085,25 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 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 @@ -5094,12 +5111,14 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 2 bait xyz Note that when replacing multiple ``bool`` or ``datetime64`` objects, - the data types in the ``to_replace`` parameter must match the data + the data types in the `to_replace` parameter must match the data type of the value being replaced: >>> df = pd.DataFrame({'A': [True, False, True], ... 'B': [False, True, False]}) >>> df.replace({'a string': 'new value', True: False}) # raises + Traceback (most recent call last): + ... TypeError: Cannot compare types 'ndarray(dtype=bool)' and 'str' This raises a ``TypeError`` because one of the ``dict`` keys is not of @@ -5107,16 +5126,15 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): Compare the behavior of ``s.replace({'a': None})`` and ``s.replace('a', None)`` to understand the pecularities - of the ``to_replace`` parameter: + of the `to_replace` parameter: >>> s = pd.Series([10, 'a', 'a', 'b', 'a']) - When one uses a dict as the ``to_replace`` value, it is like the - value(s) in the dict are equal to the value parameter. + When one uses a dict as the `to_replace` value, it is like the + value(s) in the dict are equal to the `value` parameter. ``s.replace({'a': None})`` is equivalent to ``s.replace(to_replace={'a': None}, value=None, method=None)``: - >>> #s.replace(to_replace={'a': None}, value=None, method=None) >>> s.replace({'a': None}) 0 10 1 None @@ -5125,14 +5143,13 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): 4 None dtype: object - When ``value=None`` and ``to_replace`` are a scalar, list or - tuple, ``replace`` uses the method parameter (default 'pad') to do the + When ``value=None`` and `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. The command ``s.replace('a', None)`` is actually equivalent to ``s.replace(to_replace='a', value=None, method='pad')``: - >>> #s.replace(to_replace='a', value=None, method='pad') >>> s.replace('a', None) 0 10 1 10 From cf6d6552fbc360efb8d6c7ee97eee907f3efc2b6 Mon Sep 17 00:00:00 2001 From: Gjelt Date: Sat, 21 Apr 2018 19:22:47 +0200 Subject: [PATCH 7/8] DOC: update the pandas.DataFrame.replace docstring minor change as requested --- pandas/core/generic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8e0027d1b1b43..760909d73244d 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4957,7 +4957,7 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): See Also -------- - %(klass)s.fillna : Fill `NaN` values + %(klass)s.fillna : Fill NA values %(klass)s.where : Replace values based on boolean condition Series.str.replace : Simple string replacement. From 58f6531d9f57c808d95574270b020b675ed888ed Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sat, 21 Apr 2018 13:43:34 -0500 Subject: [PATCH 8/8] Fixed linting --- pandas/core/generic.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 760909d73244d..5534d21b43ff7 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -4953,7 +4953,8 @@ def bfill(self, axis=None, inplace=False, limit=None, downcast=None): .. versionchanged:: 0.23.0 Added to DataFrame. axis : None - Deprecated. + .. deprecated:: 0.13.0 + Has no effect and will be removed. See Also --------