Skip to content

DOC: Clarify DataFrame.combine_first and Series.combine_first #40279

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 3 commits into from
Mar 8, 2021
Merged

DOC: Clarify DataFrame.combine_first and Series.combine_first #40279

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e5a83e4
clarify Series.combine_first docs
HeidiNeuhaeuser Mar 6, 2021
23f89db
DOC: Update Series.combine_first docs
HeidiNeuhaeuser Mar 7, 2021
5128c8d
DOC: Break long line
HeidiNeuhaeuser Mar 7, 2021
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
1 change: 1 addition & 0 deletions pandas/core/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6772,6 +6772,7 @@ def combine_first(self, other: DataFrame) -> DataFrame:
Returns
-------
DataFrame
The result of combining the provided DataFrame with the other object.

See Also
--------
Expand Down
23 changes: 19 additions & 4 deletions pandas/core/series.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2989,12 +2989,15 @@ def combine(self, other, func, fill_value=None) -> Series:

def combine_first(self, other) -> Series:
"""
Combine Series values, choosing the calling Series's values first.
Update null elements with value in the same location in 'other'.

Combine two Series objects by filling null values in one Series with
non-null values from the other Series.
Copy link
Member

Choose a reason for hiding this comment

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

per the corresponding line in frame.py, perhaps mention that the resulting index will be the union of the two?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It was in the "Notes" section, I moved that for consistency.


Parameters
----------
other : Series
The value(s) to be combined with the `Series`.
The value(s) to be used for filling null values in `Series`.
Copy link
Member

Choose a reason for hiding this comment

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

perhaps just "The value(s) to be used for filling null values"?


Returns
-------
Expand All @@ -3003,7 +3006,7 @@ def combine_first(self, other) -> Series:

See Also
--------
Series.combine : Perform elementwise operation on two Series
Series.combine : Perform element-wise operation on two Series
using a given function.

Notes
Expand All @@ -3013,10 +3016,22 @@ def combine_first(self, other) -> Series:
Examples
--------
>>> s1 = pd.Series([1, np.nan])
>>> s2 = pd.Series([3, 4])
>>> s2 = pd.Series([3, 4, 5])
>>> s1.combine_first(s2)
0 1.0
1 4.0
2 5.0
dtype: float64

Null values still persist if the location of that null value
does not exist in `other`

>>> s1 = pd.Series({'falcon': np.nan, 'eagle': 160.0})
>>> s2 = pd.Series({'eagle': 200.0, 'duck': 30.0})
>>> s1.combine_first(s2)
duck 30.0
eagle 160.0
falcon NaN
dtype: float64
"""
new_index = self.index.union(other.index)
Expand Down