diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 911d6fbfadd5d..4099672734f5d 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -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 -------- diff --git a/pandas/core/series.py b/pandas/core/series.py index e1a6c6884e003..74e63ef9e5ba6 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -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)