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 4 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
153 changes: 76 additions & 77 deletions pandas/core/frame.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6440,123 +6440,122 @@ def append(self, other, ignore_index=False,
def join(self, other, on=None, how='left', lsuffix='', rsuffix='',
sort=False):
"""
Join columns with other DataFrame either on index or on a key
column. Efficiently Join multiple DataFrame objects by index at once by
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, 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
how : {'left', 'right', 'outer', 'inner'}, default: 'left'
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`'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`'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
on is specified) with `other`'s index, preserving the order
of the calling's one.
lsuffix : str, default ''
Suffix to use from left frame's overlapping columns.
rsuffix : 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).

Returns
-------
DataFrame
A dataframe containing columns from both the caller and `other`.

Notes
-----
on, lsuffix, and rsuffix options are not supported when passing a list
of DataFrame objects
Options `on`, `lsuffix`, and `rsuffix` options are not supported
when passing a list of DataFrame objects.

Support for specifying index levels as the `on` parameter was added
in version 0.23.0
in version 0.23.0.

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

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
>>> 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 ``df``. This method preserves the original DataFrame's
Copy link
Member

Choose a reason for hiding this comment

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

The double backticks is for code, and the single backticks for objects that are being referenced. We don't have an exact convention for things like the parameters or the variables. Can you leave them with single backticks for now, as it's inconsistent to have df with double, and the rest like other with single. Other than that, the PR looks great.

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

Returns
-------
joined : DataFrame
>>> 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
"""
# For SparseDataFrame's benefit
return self._join_compat(other, on=on, how=how, lsuffix=lsuffix,
Expand Down