Skip to content

DOC: Clarify and add fill_value example in arithmetic ops #19675

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Feb 22, 2018
Merged

DOC: Clarify and add fill_value example in arithmetic ops #19675

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
24d704a
Clarified fill_value parameter in arithmetic ops
HagaiHargil Feb 13, 2018
b5d9d6f
Add fill_value change to DF
HagaiHargil Feb 13, 2018
c45dbd9
Add fill_value example to DF
HagaiHargil Feb 13, 2018
b2794d9
Rephrasing and PEP8 fixes
HagaiHargil Feb 13, 2018
13f1f00
Two-columned DataFrame
HagaiHargil Feb 18, 2018
1bf321c
dict constructor and rephrasing
HagaiHargil Feb 18, 2018
fd89953
Variables are now displayed before operation
HagaiHargil Feb 19, 2018
af0aebe
Fixed bug with format and dict constructor
HagaiHargil Feb 20, 2018
3192301
Changes index from c_ to e
HagaiHargil Feb 21, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 90 additions & 7 deletions pandas/core/ops.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,8 +255,10 @@ def _get_frame_op_default_axis(name):
----------
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
Fill existing missing (NaN) values, and any new element needed for
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove the 'and any new elemnt needed for successful array alignment', this is redundant with your last sentence.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure which sentence are you referring to. The "and any new element needed" sentence refers to the alignment process. The last sentence ("If data in both corresponding...") only deals with a "corner case" of two NaNs, without any direct reference to the data alignment process.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't use the word 'array' as these are not arrays. this is still not very clear.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this phrasing much better. Could you change "new element" to "new missing values"

You can remove the commas around the "and any new element... " clause.

successful Series alignment, with this value before computation.
If data in both corresponding Series locations is missing
the result will be missing
level : int or name
Broadcast across a level, matching Index values on the
passed MultiIndex level
Expand All @@ -265,6 +267,30 @@ def _get_frame_op_default_axis(name):
-------
result : Series

Examples
--------
>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

show a and b as well

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to have a line with just >>> a on it before showing the Series. Likewise for b.

>>> a
a 1.0
b 1.0
c 1.0
d NaN
dtype: float64
>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
>>> b
a 1.0
b NaN
d 1.0
e NaN
dtype: float64
>>> a.add(b, fill_value=0)
a 2.0
b 1.0
c 1.0
d 1.0
e NaN
dtype: float64

See also
--------
Series.{reverse}
Expand All @@ -280,8 +306,10 @@ def _get_frame_op_default_axis(name):
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
Fill existing missing (NaN) values, and any new element needed for
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same

successful DataFrame alignment, with this value before computation.
If data in both corresponding DataFrame locations is missing
the result will be missing
level : int or name
Broadcast across a level, matching Index values on the
passed MultiIndex level
Expand All @@ -293,6 +321,33 @@ def _get_frame_op_default_axis(name):
Returns
-------
result : DataFrame

Examples
--------
>>> a = pd.DataFrame([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'],
columns=['one'])
>>> a
one
a 1.0
b 1.0
c 1.0
d NaN
>>> b = pd.DataFrame(dict(one=[1, np.nan, 1, np.nan],
two=[np.nan, 2, np.nan, 2]),
index=['a', 'b', 'd', 'e'])
>>> b
one two
a 1.0 NaN
b NaN 2.0
d 1.0 NaN
e NaN 2.0
>>> a.add(b, fill_value=0)
one two
a 2.0 NaN
b 1.0 2.0
c 1.0 NaN
d 1.0 NaN
e NaN 2.0
"""

_flex_doc_FRAME = """
Expand All @@ -307,8 +362,10 @@ def _get_frame_op_default_axis(name):
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
Fill existing missing (NaN) values, and any new element needed for
successful DataFrame alignment, with this value before computation.
If data in both corresponding DataFrame locations is missing
the result will be missing
level : int or name
Broadcast across a level, matching Index values on the
passed MultiIndex level
Expand All @@ -321,6 +378,33 @@ def _get_frame_op_default_axis(name):
-------
result : DataFrame

Examples
--------
>>> a = pd.DataFrame([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'],
columns=['one'])
>>> a
one
a 1.0
b 1.0
c 1.0
d NaN
>>> b = pd.DataFrame(dict(one=[1, np.nan, 1, np.nan],
two=[np.nan, 2, np.nan, 2]),
index=['a', 'b', 'd', 'e'])
>>> b
one two
a 1.0 NaN
b NaN 2.0
d 1.0 NaN
e NaN 2.0
>>> a.add(b, fill_value=0)
one two
a 2.0 NaN
b 1.0 2.0
c 1.0 NaN
d 1.0 NaN
e NaN 2.0

See also
--------
DataFrame.{reverse}
Expand Down Expand Up @@ -392,7 +476,6 @@ def _make_flex_doc(op_name, typ):
base_doc = _flex_doc_PANEL
else:
raise AssertionError('Invalid typ argument.')

doc = base_doc.format(desc=op_desc['desc'], op_name=op_name,
equiv=equiv, reverse=op_desc['reverse'])
return doc
Expand Down