Series replace, unexpected fill behavior

[rasmuse]

Many thanks for the excellent software. This report is about behavior I did not expect. Not sure if it is a bug or not.

>>> import pandas as pd
>>> 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

Problem description

This behavior was unexpected for me. I would have assumed that these two lines would produce the same output:

s.replace('a', None)
s.replace({'a': None})

In my particular use case, I was actually looking to just replace 'a'with None and therefore did s.replace('a', None). I did not check output carefully and therefore ended up with some very strange behavior down the line in my data analysis.

Not sure if this is to be considered a bug or not. Docs are not entirely clear on what is intended behavior. Possible solutions could include

• Describe behavior in docs (the filling behavior is barely described at all).
• Hint that something like s.replace('a', numpy.nan) might be a better option.
• Change API to require a more explicit opt-in for filling.

Output of pd.show_versions()

INSTALLED VERSIONS

commit: None
python: 3.6.4.final.0
python-bits: 64
OS: Linux
OS-release: 4.4.0-116-generic
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: en_US.UTF-8

pandas: 0.22.0
pytest: None
pip: 9.0.1
setuptools: 38.5.1
Cython: None
numpy: 1.14.0
scipy: None
pyarrow: None
xarray: None
IPython: None
sphinx: None
patsy: None
dateutil: 2.6.1
pytz: 2018.3
blosc: None
bottleneck: None
tables: None
numexpr: None
feather: None
matplotlib: None
openpyxl: None
xlrd: None
xlwt: None
xlsxwriter: None
lxml: None
bs4: None
html5lib: None
sqlalchemy: None
pymysql: None
psycopg2: None
jinja2: None
s3fs: None
fastparquet: None
pandas_gbq: None
pandas_datareader: None

[reidy-p]

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's like the value(s) in the dict are equal to the value parameter. This behaviour has also caused some confusion for me in the past.

I agree that the docs for replace are not always very clear but I think this is partly because it has so much functionality (maybe too much). I have worked on improving the replace docs a little bit and an improved version will be in the next release but additional clarifications are always welcome (issue #17673).

[gfyoung]

@reidy-p : Excellent explanation!

[rasmuse]

Thanks @reidy-p for details and the very relevant link to #17673. I would agree with your assessment that replace has perhaps too much functionality. I would prefer an API where fill and replace are clearly separated operations. Another possibility could be to change the API to say something like fill='pad' explicitly. But I realize breaking changes in APIs cannot be made just like that.

So, if the task is to improve the docstring, my concrete suggestion is this: Clarify under the value parameter of replace that None is not treated as a replacement value, but as a request for fill behavior according to the method parameter.

Many thanks for your excellent work.

[reidy-p]

I would prefer an API where fill and replace are clearly separated operations. Another possibility could be to change the API to say something like fill='pad' explicitly. But I realize breaking changes in APIs cannot be made just like that.

These are good suggestions. I think it would be good if the method parameter is only used when explicitly called rather than by default because it's quite easy to get unexpected behaviour at present as you have shown. If it doesn't break the API substantially I would prefer if the behaviour of s.replace('a', None) is the same as s.replace({'a': None}).

@gfyoung what do you think of this idea?

If this isn't possible, then I think we should at least add the docstring improvement suggested by @rasmuse