DOC: Clarifiy fill_value behavior in arithmetic ops

[HagaiHargil]

When adding two DataFrames using df1.add(df2) one can use the fill_value parameter to fill in any NaNs that might come up. This parameter seems pretty broken:

a = pd.DataFrame(np.ones((3, 2)))
b = pd.DataFrame(np.ones((4, 3)))
print(a + b)  # all good:
#      0    1   2
# 0  2.0  2.0 NaN
# 1  2.0  2.0 NaN
# 2  2.0  2.0 NaN
# 3  NaN  NaN NaN

print(a.add(b))  # all good
print(a.add(b, fill_value=0))  # broken
#      0    1    2
# 0  2.0  2.0  1.0
# 1  2.0  2.0  1.0
# 2  2.0  2.0  1.0
# 3  1.0  1.0  1.0

As you see, it filled the NaNs with 1.0. Changing fill_value=1 will fill everything with 2.0. However, changing some of the values inside b leads to more peculiar results, and I couldn't really connect the dots and find some pattern.

This was observed on Python 3.6 on both Linux and Windows.

Thanks.

``` commit: None python: 3.6.3.final.0 python-bits: 64 OS: Linux OS-release: 3.10.0-514.el7.x86_64 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.4.0 Cython: 0.27.3 numpy: 1.14.0 scipy: 1.0.0 pyarrow: None xarray: None IPython: 6.2.1 sphinx: 1.6.7 patsy: None dateutil: 2.6.1 pytz: 2017.3 blosc: None bottleneck: None tables: None numexpr: None feather: None matplotlib: 2.1.1 openpyxl: None xlrd: None xlwt: None xlsxwriter: None lxml: None bs4: None html5lib: 0.9999999 sqlalchemy: None pymysql: None psycopg2: None jinja2: 2.10 s3fs: None fastparquet: None pandas_gbq: None pandas_datareader: None ```

[jreback]

pls read the documentation. This is doing an align then a fillna operation.

In [1]: a = pd.DataFrame(np.ones((3, 2))) * 2
   ...: b = pd.DataFrame(np.ones((4, 3)))
   ...: 

In [2]: a
Out[2]: 
     0    1
0  2.0  2.0
1  2.0  2.0
2  2.0  2.0

In [3]: b
Out[3]: 
     0    1    2
0  1.0  1.0  1.0
1  1.0  1.0  1.0
2  1.0  1.0  1.0
3  1.0  1.0  1.0

In [4]: ax, bx = a.align(b)

In [5]: ax
Out[5]: 
     0    1   2
0  2.0  2.0 NaN
1  2.0  2.0 NaN
2  2.0  2.0 NaN
3  NaN  NaN NaN

In [6]: bx
Out[6]: 
     0    1    2
0  1.0  1.0  1.0
1  1.0  1.0  1.0
2  1.0  1.0  1.0
3  1.0  1.0  1.0

In [7]: ax.fillna(0) + bx.fillna(0)
Out[7]: 
     0    1    2
0  3.0  3.0  1.0
1  3.0  3.0  1.0
2  3.0  3.0  1.0
3  1.0  1.0  1.0

In [8]: a.add(b,fill_value=0)
Out[8]: 
     0    1    2
0  3.0  3.0  1.0
1  3.0  3.0  1.0
2  3.0  3.0  1.0
3  1.0  1.0  1.0

[HagaiHargil]

Hi,

I wouldn't post a GitHub issue without reading the documentation first :)

The documentation can be understood both ways, and actually I think that my "explanation" is more intuitive and straight-forward.

It currently simply states that:

fill_value: Fill missing (NaN) values with this value. If both DataFrame locations are missing, the result will be missing.

It's very unclear that it refers to two types of NaN values - (a) the ones that already exist in the data, (b) and the ones that are generated after the alignment step and before the addition step - but does not include the NaNs that are visible after a simple addition of the dataframes, which are the most relevant to the end user.

At the least I believe that the documentation should be edited, won't you think?

[jreback]

you are welcome to PR a doc update if u think it is not clear

[TomAugspurger]

Yep, I can see the point of confusion.

@HagaiHargil are you comfortable making a PR clarifying things?

pandas/pandas/core/ops.py

Lines 248 to 259 in a277108

	_flex_doc_SERIES = """
	{desc} of series and other, element-wise (binary operator `{op_name}`).
	Equivalent to ``{equiv}``, but with support to substitute a fill_value for
	missing data in one of the inputs.
	Parameters
	----------
	other : Series or scalar value
	fill_value : None or float value, default None (NaN)
	Fill missing (NaN) values with this value. If both Series are
	missing, the result will be missing

and

pandas/pandas/core/ops.py

Lines 273 to 284 in a277108

	_arith_doc_FRAME = """
	Binary operator %s with support to substitute a fill_value for missing data in
	one of the inputs
	Parameters
	----------
	other : Series, DataFrame, or constant
	axis : {0, 1, 'index', 'columns'}
	For Series input, axis to match Series index on
	fill_value : None or float value, default None
	Fill missing (NaN) values with this value. If both DataFrame locations are
	missing, the result will be missing