From 4377e47b18b1f6a68ad16dded5010c5fb7e273b2 Mon Sep 17 00:00:00 2001 From: Triple0 Date: Sun, 11 Mar 2018 01:06:26 +0100 Subject: [PATCH 1/9] DOC: Improve the docstring of pandas.DataFrame.append() --- pandas/core/frame.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index a66d00fff9714..0dc5d6bcb9861 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -5054,7 +5054,9 @@ def infer(x): def append(self, other, ignore_index=False, verify_integrity=False): """ Append rows of `other` to the end of this frame, returning a new - object. Columns not in this frame are added as new columns. + object. + + Columns not in this frame are added as new columns. Parameters ---------- @@ -5136,7 +5138,6 @@ def append(self, other, ignore_index=False, verify_integrity=False): 2 2 3 3 4 4 - """ if isinstance(other, (Series, dict)): if isinstance(other, dict): From 01af9d1edee391c1c9e7316e34111a29482b1a66 Mon Sep 17 00:00:00 2001 From: Triple0 Date: Sun, 11 Mar 2018 01:51:56 +0100 Subject: [PATCH 2/9] DOC: Improve the docstring of pandas.DataFrame.append() --- pandas/core/frame.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 0dc5d6bcb9861..5b8e950bf0ac9 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -5053,10 +5053,9 @@ def infer(x): def append(self, other, ignore_index=False, verify_integrity=False): """ - Append rows of `other` to the end of this frame, returning a new - object. + Append rows of `other` to the end of `caller`, returning a new object. - Columns not in this frame are added as new columns. + Columns not in the caller are added as new columns. Parameters ---------- From 1ffcece50e371dbb071a6bfab1ba962fbfd70c9f Mon Sep 17 00:00:00 2001 From: Triple0 Date: Sun, 11 Mar 2018 10:35:49 +0100 Subject: [PATCH 3/9] DOC: Improve the docstring of pandas.DataFrame.append() --- pandas/core/frame.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 5b8e950bf0ac9..daea6a975efcf 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -5055,7 +5055,7 @@ def append(self, other, ignore_index=False, verify_integrity=False): """ Append rows of `other` to the end of `caller`, returning a new object. - Columns not in the caller are added as new columns. + Columns not in other are added as new columns. Parameters ---------- From 6c3946a8037795d43766cb674ed30be47f3a54ec Mon Sep 17 00:00:00 2001 From: Triple0 Date: Sun, 11 Mar 2018 12:45:06 +0100 Subject: [PATCH 4/9] DOC: Improve the docstring of pandas.DataFrame.assign() --- pandas/core/frame.py | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index daea6a975efcf..b6a102f3ab18a 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -143,14 +143,16 @@ ----------%s right : DataFrame how : {'left', 'right', 'outer', 'inner'}, default 'inner' + How to handle the operation of the two objects. + * left: use only keys from left frame, similar to a SQL left outer join; - preserve key order + preserve key order. * right: use only keys from right frame, similar to a SQL right outer join; - preserve key order + preserve key order. * outer: use union of keys from both frames, similar to a SQL full outer - join; sort keys lexicographically + join; sort keys lexicographically. * inner: use intersection of keys from both frames, similar to a SQL inner - join; preserve the order of the left keys + join; preserve the order of the left keys. on : label or list Column or index level names to join on. These must be found in both DataFrames. If `on` is None and not merging on indexes then this defaults @@ -166,18 +168,18 @@ left_index : boolean, default False Use the index from the left DataFrame as the join key(s). If it is a MultiIndex, the number of keys in the other DataFrame (either the index - or a number of columns) must match the number of levels + or a number of columns) must match the number of levels. right_index : boolean, default False Use the index from the right DataFrame as the join key. Same caveats as - left_index + left_index. sort : boolean, default False Sort the join keys lexicographically in the result DataFrame. If False, - the order of the join keys depends on the join type (how keyword) + the order of the join keys depends on the join type (how keyword). suffixes : 2-length sequence (tuple, list, ...) Suffix to apply to overlapping column names in the left and right - side, respectively + side, respectively. copy : boolean, default True - If False, do not copy data unnecessarily + If False, do not copy data unnecessarily. indicator : boolean or string, default False If True, adds a column to output DataFrame called "_merge" with information on the source of each row. @@ -199,7 +201,7 @@ dataset. * "many_to_many" or "m:m": allowed, but does not result in checks. - .. versionadded:: 0.21.0 + .. versionadded:: 0.21.0. Notes ----- @@ -2689,7 +2691,7 @@ def insert(self, loc, column, value, allow_duplicates=False): allow_duplicates=allow_duplicates) def assign(self, **kwargs): - r""" + """ Assign new columns to a DataFrame, returning a new object (a copy) with all the original columns in addition to the new ones. @@ -5402,7 +5404,6 @@ def round(self, decimals=0, *args, **kwargs): -------- numpy.around Series.round - """ from pandas.core.reshape.concat import concat From 083afccbbc6ee23b569a9b8e81d5b3000b51020e Mon Sep 17 00:00:00 2001 From: Triple0 Date: Sun, 11 Mar 2018 15:57:43 +0100 Subject: [PATCH 5/9] DOC: Improve the docstring of pandas.DataFrame.merge() --- pandas/core/frame.py | 53 ++++++++++++++++++++++++++++---------------- 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index b6a102f3ab18a..a94d7e0202704 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -140,7 +140,7 @@ columns, the index will be passed on. Parameters -----------%s +---------- right : DataFrame how : {'left', 'right', 'outer', 'inner'}, default 'inner' How to handle the operation of the two objects. @@ -211,21 +211,31 @@ Examples -------- ->>> A >>> B - lkey value rkey value -0 foo 1 0 foo 5 -1 bar 2 1 bar 6 -2 baz 3 2 qux 7 -3 foo 4 3 bar 8 +>>> A = pd.DataFrame({'lkey': ['foo', 'bar', 'baz', 'foo'], +... 'value': [1, 2, 3, 5]}) +>>> B = pd.DataFrame({'rkey': ['foo', 'bar', 'baz', 'foo'], +... 'value': [5, 6, 7, 8]}) +>>> A + lkey value +0 foo 1 +1 bar 2 +2 baz 3 +3 foo 4 +>>> B + rkey value +0 foo 5 +1 bar 6 +2 baz 7 +3 foo 8 >>> A.merge(B, left_on='lkey', right_on='rkey', how='outer') - lkey value_x rkey value_y -0 foo 1 foo 5 -1 foo 4 foo 5 -2 bar 2 bar 6 -3 bar 2 bar 8 -4 baz 3 NaN NaN -5 NaN NaN qux 7 + lkey value_x rkey value_y +0 foo 1 foo 5 +1 foo 1 foo 8 +2 foo 5 foo 5 +3 foo 5 foo 8 +4 bar 2 bar 6 +5 baz 3 baz 7 Returns ------- @@ -2692,13 +2702,14 @@ def insert(self, loc, column, value, allow_duplicates=False): def assign(self, **kwargs): """ - Assign new columns to a DataFrame, returning a new object - (a copy) with all the original columns in addition to the new ones. + Assign new columns to a DataFrame. + + Returns a new object with all original columns in addition to new ones. Parameters ---------- kwargs : keyword, value pairs - keywords are the column names. If the values are + The column names are keywords. If the values are callable, they are computed on the DataFrame and assigned to the new columns. The callable must not change input DataFrame (though pandas doesn't check it). @@ -2721,9 +2732,13 @@ def assign(self, **kwargs): or modified columns. All items are computed first, and then assigned in alphabetical order. - .. versionchanged :: 0.23.0 + .. versionchanged :: 0.23.0. + + Keyword argument order is maintained for Python 3.6 and later. - Keyword argument order is maintained for Python 3.6 and later. + See Also + -------- + DataFrame.assign: For column(s)-on-DataFrame operations Examples -------- From 389d7eee594f70b24ee49f9beed7c86920107cf4 Mon Sep 17 00:00:00 2001 From: Triple0 Date: Sun, 11 Mar 2018 19:10:36 +0100 Subject: [PATCH 6/9] DOC: Improve the docstring of pandas.DataFrame.merge() --- pandas/core/frame.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index a94d7e0202704..cd973ae48b57a 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -141,18 +141,18 @@ Parameters ---------- -right : DataFrame +right : DataFrame or Series/dict-like object how : {'left', 'right', 'outer', 'inner'}, default 'inner' How to handle the operation of the two objects. * left: use only keys from left frame, similar to a SQL left outer join; - preserve key order. + preserve key order * right: use only keys from right frame, similar to a SQL right outer join; - preserve key order. + preserve key order * outer: use union of keys from both frames, similar to a SQL full outer - join; sort keys lexicographically. + join; sort keys lexicographically * inner: use intersection of keys from both frames, similar to a SQL inner - join; preserve the order of the left keys. + join; preserve the order of the left keys on : label or list Column or index level names to join on. These must be found in both DataFrames. If `on` is None and not merging on indexes then this defaults @@ -249,11 +249,9 @@ merge_asof DataFrame.join """ - # ----------------------------------------------------------------------- # DataFrame class - class DataFrame(NDFrame): """ Two-dimensional size-mutable, potentially heterogeneous tabular data structure with labeled axes (rows and columns). Arithmetic operations From cb78862599876bf1f3f98be2c0b55673b0d250c6 Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sun, 8 Jul 2018 11:11:20 -0500 Subject: [PATCH 7/9] DOC fixup --- pandas/core/frame.py | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index cd973ae48b57a..5810dfccf47a7 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -141,7 +141,7 @@ Parameters ---------- -right : DataFrame or Series/dict-like object +right : DataFrame, Series or dict how : {'left', 'right', 'outer', 'inner'}, default 'inner' How to handle the operation of the two objects. @@ -165,22 +165,22 @@ Column or index level names to join on in the right DataFrame. Can also be an array or list of arrays of the length of the right DataFrame. These arrays are treated as if they are columns. -left_index : boolean, default False +left_index : boolean, default `False` Use the index from the left DataFrame as the join key(s). If it is a MultiIndex, the number of keys in the other DataFrame (either the index or a number of columns) must match the number of levels. -right_index : boolean, default False +right_index : boolean, default `False` Use the index from the right DataFrame as the join key. Same caveats as left_index. -sort : boolean, default False - Sort the join keys lexicographically in the result DataFrame. If False, +sort : boolean, default `False` + Sort the join keys lexicographically in the result DataFrame. If `False`, the order of the join keys depends on the join type (how keyword). suffixes : 2-length sequence (tuple, list, ...) Suffix to apply to overlapping column names in the left and right side, respectively. copy : boolean, default True - If False, do not copy data unnecessarily. -indicator : boolean or string, default False + If `False`, do not copy data unnecessarily. +indicator : boolean or string, default `False` If True, adds a column to output DataFrame called "_merge" with information on the source of each row. If string, column with information on source of each row will be added to @@ -201,7 +201,7 @@ dataset. * "many_to_many" or "m:m": allowed, but does not result in checks. - .. versionadded:: 0.21.0. + .. versionadded:: 0.21.0 Notes ----- @@ -249,9 +249,11 @@ merge_asof DataFrame.join """ + # ----------------------------------------------------------------------- # DataFrame class + class DataFrame(NDFrame): """ Two-dimensional size-mutable, potentially heterogeneous tabular data structure with labeled axes (rows and columns). Arithmetic operations @@ -2699,7 +2701,7 @@ def insert(self, loc, column, value, allow_duplicates=False): allow_duplicates=allow_duplicates) def assign(self, **kwargs): - """ + r""" Assign new columns to a DataFrame. Returns a new object with all original columns in addition to new ones. @@ -2730,13 +2732,9 @@ def assign(self, **kwargs): or modified columns. All items are computed first, and then assigned in alphabetical order. - .. versionchanged :: 0.23.0. - - Keyword argument order is maintained for Python 3.6 and later. + .. versionchanged :: 0.23.0 - See Also - -------- - DataFrame.assign: For column(s)-on-DataFrame operations + Keyword argument order is maintained for Python 3.6 and later. Examples -------- @@ -5068,9 +5066,9 @@ def infer(x): def append(self, other, ignore_index=False, verify_integrity=False): """ - Append rows of `other` to the end of `caller`, returning a new object. + Append rows of `other` to the end of caller, returning a new object. - Columns not in other are added as new columns. + Columns in `other` that are not in the caller are added as new columns. Parameters ---------- From 023ed83c787058a053b3572c489c5b7ec5ce6e9f Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sun, 8 Jul 2018 11:24:02 -0500 Subject: [PATCH 8/9] DOC fixup --- pandas/core/frame.py | 55 ++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index ce94b0d9b5bf6..5903ecf5cb761 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -144,10 +144,11 @@ columns, the index will be passed on. Parameters ----------- +----------%s right : DataFrame, Series or dict + Object to merge with. how : {'left', 'right', 'outer', 'inner'}, default 'inner' - How to handle the operation of the two objects. + Type of merge to be performed. * left: use only keys from left frame, similar to a SQL left outer join; preserve key order @@ -169,22 +170,22 @@ Column or index level names to join on in the right DataFrame. Can also be an array or list of arrays of the length of the right DataFrame. These arrays are treated as if they are columns. -left_index : boolean, default `False` +left_index : boolean, default False Use the index from the left DataFrame as the join key(s). If it is a MultiIndex, the number of keys in the other DataFrame (either the index or a number of columns) must match the number of levels. -right_index : boolean, default `False` +right_index : boolean, default False Use the index from the right DataFrame as the join key. Same caveats as left_index. -sort : boolean, default `False` - Sort the join keys lexicographically in the result DataFrame. If `False`, +sort : boolean, default False + Sort the join keys lexicographically in the result DataFrame. If False, the order of the join keys depends on the join type (how keyword). suffixes : 2-length sequence (tuple, list, ...) Suffix to apply to overlapping column names in the left and right side, respectively. copy : boolean, default True - If `False`, do not copy data unnecessarily. -indicator : boolean or string, default `False` + If False, do not copy data unnecessarily. +indicator : boolean or string, default False If True, adds a column to output DataFrame called "_merge" with information on the source of each row. If string, column with information on source of each row will be added to @@ -207,11 +208,21 @@ .. versionadded:: 0.21.0 +Returns +------- +DataFrame + Notes ----- Support for specifying index levels as the `on`, `left_on`, and `right_on` parameters was added in version 0.23.0 +See Also +-------- +merge_ordered : merge with optional filling/interpolation. +merge_asof : merge on nearest keys. +DataFrame.join : similar method using indices. + Examples -------- @@ -221,16 +232,16 @@ ... 'value': [5, 6, 7, 8]}) >>> A lkey value -0 foo 1 -1 bar 2 -2 baz 3 -3 foo 4 +0 foo 1 +1 bar 2 +2 baz 3 +3 foo 5 >>> B rkey value -0 foo 5 -1 bar 6 -2 baz 7 -3 foo 8 +0 foo 5 +1 bar 6 +2 baz 7 +3 foo 8 >>> A.merge(B, left_on='lkey', right_on='rkey', how='outer') lkey value_x rkey value_y @@ -240,18 +251,6 @@ 3 foo 5 foo 8 4 bar 2 bar 6 5 baz 3 baz 7 - -Returns -------- -merged : DataFrame - The output type will the be same as 'left', if it is a subclass - of DataFrame. - -See also --------- -merge_ordered -merge_asof -DataFrame.join """ # ----------------------------------------------------------------------- From cb9ee7752950f44e8db92f725892176a7e833876 Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sun, 8 Jul 2018 11:27:08 -0500 Subject: [PATCH 9/9] Updated copy description --- pandas/core/frame.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 5903ecf5cb761..fa720bb38213f 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -184,7 +184,7 @@ Suffix to apply to overlapping column names in the left and right side, respectively. copy : boolean, default True - If False, do not copy data unnecessarily. + If False, avoid copy if possible. indicator : boolean or string, default False If True, adds a column to output DataFrame called "_merge" with information on the source of each row.