Skip to content

DOC GH22897 Fix docstring of join in pandas/core/frame.py #22904

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

Closed
wants to merge 8 commits into from
Closed

DOC GH22897 Fix docstring of join in pandas/core/frame.py #22904

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
cf56698
DOC GH22897 Fix docstring of join in pandas/core/frame.py
JustinZhengBC Sep 30, 2018
988c40c
DOC GH22897 Fix other formatting issues in pandas/core/frame.py
JustinZhengBC Sep 30, 2018
8139490
DOC GH22897 Fix additional formatting issues in pandas/core/frame.py
JustinZhengBC Sep 30, 2018
762f66d
DOC GH22897 Modified previous commit to use double backticks when app…
JustinZhengBC Sep 30, 2018
19725a4
Revert "DOC GH22897 Fix additional formatting issues in pandas/core/f…
JustinZhengBC Sep 30, 2018
32b475d
Revert "Revert "DOC GH22897 Fix additional formatting issues in panda…
JustinZhengBC Sep 30, 2018
69f81dc
Merge branch 'DOC-22897' of https://github.com/JustinZhengBC/pandas i…
JustinZhengBC Sep 30, 2018
05988d4
DOC GH22897 Undo previous commit
JustinZhengBC Sep 30, 2018
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
124 changes: 61 additions & 63 deletions pandas/core/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6440,40 +6440,42 @@ def append(self, other, ignore_index=False,
def join(self, other, on=None, how='left', lsuffix='', rsuffix='',
sort=False):
"""
Join columns of another DataFrame.

Join columns with other DataFrame either on index or on a key
column. Efficiently Join multiple DataFrame objects by index at once by
passing a list.

Parameters
----------
other : DataFrame, Series with name field set, or list of DataFrame
other : DataFrame, Series, or list of DataFrame
Index should be similar to one of the columns in this one. If a
Series is passed, its name attribute must be set, and that will be
used as the column name in the resulting joined DataFrame
on : name, tuple/list of names, or array-like
used as the column name in the resulting joined DataFrame.
on : str, list of str, or array-like
Copy link
Member

Choose a reason for hiding this comment

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

can you add that it's optional: on : str, list of str, or array-like, optional

Column or index level name(s) in the caller to join on the index
in `other`, otherwise joins index-on-index. If multiple
values given, the `other` DataFrame must have a MultiIndex. Can
pass an array as the join key if it is not already contained in
the calling DataFrame. Like an Excel VLOOKUP operation
the calling DataFrame. Like an Excel VLOOKUP operation.
how : {'left', 'right', 'outer', 'inner'}, default: 'left'
How to handle the operation of the two objects.

* left: use calling frame's index (or column if on is specified)
* right: use other frame's index
* right: use other frame's index.
* outer: form union of calling frame's index (or column if on is
specified) with other frame's index, and sort it
lexicographically
specified) with other frame's index, and sort it.
lexicographically.
* inner: form intersection of calling frame's index (or column if
on is specified) with other frame's index, preserving the order
of the calling's one
lsuffix : string
Suffix to use from left frame's overlapping columns
rsuffix : string
Suffix to use from right frame's overlapping columns
sort : boolean, default False
of the calling's one.
lsuffix : str
Suffix to use from left frame's overlapping columns.
rsuffix : str
Copy link
Member

Choose a reason for hiding this comment

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

can you add the default: str, default ''

Suffix to use from right frame's overlapping columns.
sort : bool, default False
Order result DataFrame lexicographically by the join key. If False,
the order of the join key depends on the join type (how keyword)
the order of the join key depends on the join type (how keyword).

Notes
-----
Expand All @@ -6483,76 +6485,72 @@ def join(self, other, on=None, how='left', lsuffix='', rsuffix='',
Support for specifying index levels as the `on` parameter was added
in version 0.23.0
Copy link
Member

Choose a reason for hiding this comment

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

Do you mind capitalizing the first letter of each sentence, and ending them in period in the Notes. For the First paragraph, if you can add backticks around the parameters on, lsuffix... that would be great too. So: "Options `on`, `lsuffix` and `rsuffix` are not supported [...]"


See Also
--------
DataFrame.merge : For column(s)-on-columns(s) operations.

Examples
--------
>>> caller = pd.DataFrame({'key': ['K0', 'K1', 'K2', 'K3', 'K4', 'K5'],

>>> df = pd.DataFrame({'key': ['K0', 'K1', 'K2', 'K3', 'K4', 'K5'],
... 'A': ['A0', 'A1', 'A2', 'A3', 'A4', 'A5']})

>>> caller
A key
0 A0 K0
1 A1 K1
2 A2 K2
3 A3 K3
4 A4 K4
5 A5 K5
>>> df
key A
0 K0 A0
1 K1 A1
2 K2 A2
3 K3 A3
4 K4 A4
5 K5 A5

>>> other = pd.DataFrame({'key': ['K0', 'K1', 'K2'],
... 'B': ['B0', 'B1', 'B2']})

>>> other
B key
0 B0 K0
1 B1 K1
2 B2 K2
key B
0 K0 B0
1 K1 B1
2 K2 B2

Join DataFrames using their indexes.

>>> caller.join(other, lsuffix='_caller', rsuffix='_other')

>>> A key_caller B key_other
0 A0 K0 B0 K0
1 A1 K1 B1 K1
2 A2 K2 B2 K2
3 A3 K3 NaN NaN
4 A4 K4 NaN NaN
5 A5 K5 NaN NaN

>>> df.join(other, lsuffix='_caller', rsuffix='_other')
key_caller A key_other B
0 K0 A0 K0 B0
1 K1 A1 K1 B1
2 K2 A2 K2 B2
3 K3 A3 NaN NaN
4 K4 A4 NaN NaN
5 K5 A5 NaN NaN

If we want to join using the key columns, we need to set key to be
the index in both caller and other. The joined DataFrame will have
the index in both df and other. The joined DataFrame will have
key as its index.

>>> caller.set_index('key').join(other.set_index('key'))

>>> A B
key
K0 A0 B0
K1 A1 B1
K2 A2 B2
K3 A3 NaN
K4 A4 NaN
K5 A5 NaN
>>> df.set_index('key').join(other.set_index('key'))
A B
key
K0 A0 B0
K1 A1 B1
K2 A2 B2
K3 A3 NaN
K4 A4 NaN
K5 A5 NaN

Another option to join using the key columns is to use the on
parameter. DataFrame.join always uses other's index but we can use any
column in the caller. This method preserves the original caller's
column in df. This method preserves the original DataFrame's
index in the result.

>>> caller.join(other.set_index('key'), on='key')

>>> A key B
0 A0 K0 B0
1 A1 K1 B1
2 A2 K2 B2
3 A3 K3 NaN
4 A4 K4 NaN
5 A5 K5 NaN


See also
--------
DataFrame.merge : For column(s)-on-columns(s) operations
>>> df.join(other.set_index('key'), on='key')
key A B
0 K0 A0 B0
1 K1 A1 B1
2 K2 A2 B2
3 K3 A3 NaN
4 K4 A4 NaN
5 K5 A5 NaN

Returns
-------
Copy link
Member

Choose a reason for hiding this comment

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

Sorry, I missed before that the Returns was here. Can you move it after the parameters, and use this format:

Returns
-------
DataFrame
    A short description on what is being returned.

Expand Down