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 all commits
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
30 changes: 21 additions & 9 deletions pandas/core/series.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2989,34 +2989,46 @@ 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. Result index will be the union
of the two indexes.

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

Returns
-------
Series
The result of combining the Series with the other object.
The result of combining the provided Series with the other object.

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

Notes
-----
Result index will be the union of the two indexes.

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