From e5a83e4e72b68305f15a5669682eea9e868a8e40 Mon Sep 17 00:00:00 2001 From: Heidi Date: Sat, 6 Mar 2021 17:45:35 +0000 Subject: [PATCH 1/3] clarify Series.combine_first docs --- pandas/core/frame.py | 1 + pandas/core/series.py | 23 +++++++++++++++++++---- 2 files changed, 20 insertions(+), 4 deletions(-) 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..379d36e3c1507 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -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. Parameters ---------- other : Series - The value(s) to be combined with the `Series`. + The value(s) to be used for filling null values in `Series`. Returns ------- @@ -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 @@ -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) From 23f89db00b9a6451ccff365b9de608679d7cde37 Mon Sep 17 00:00:00 2001 From: Heidi Date: Sun, 7 Mar 2021 19:36:46 +0000 Subject: [PATCH 2/3] DOC: Update Series.combine_first docs --- pandas/core/series.py | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 379d36e3c1507..42380346d523f 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2992,27 +2992,23 @@ def combine_first(self, other) -> Series: 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. + 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 used for filling null values in `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 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]) From 5128c8db4c2b8b7e7a727539a9468e4cc5c92468 Mon Sep 17 00:00:00 2001 From: Heidi Date: Sun, 7 Mar 2021 19:39:55 +0000 Subject: [PATCH 3/3] DOC: Break long line --- pandas/core/series.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 42380346d523f..74e63ef9e5ba6 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2992,7 +2992,8 @@ def combine_first(self, other) -> Series: 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. + non-null values from the other Series. Result index will be the union + of the two indexes. Parameters ----------