The documentation for pandas.merge_ordered at https://pandas.pydata.org/pandas-docs/stable/generated/pandas.merge_ordered.html#pandas.merge_ordered presents an example in which the output is not consistent with the input.

In addition, the example for merge_ordered invokes ordered_merge, which is a deprecated function.

Code Sample

This code shows the actual output for the dataframes A and B listed in the example.

In [1]: import pandas

In [4]: A = pandas.DataFrame({'key': list('aceace'), 'lvalue': [1, 2, 3, 1, 2, 3], 'group': list('aaabbb')})[['key', 'lvalue', 'group']]

In [5]: A
Out[5]:
  key  lvalue group
0   a       1     a
1   c       2     a
2   e       3     a
3   a       1     b
4   c       2     b
5   e       3     b

In [7]: B = pandas.DataFrame({'key': list('bcd'), 'rvalue': [1, 2, 3]})[['key', 'rvalue']]

In [8]: B
Out[8]:
  key  rvalue
0   b       1
1   c       2
2   d       3

In [9]: pandas.ordered_merge(A, B, fill_method='ffill', left_by='group')
C:\hbkbin\conda\envs\066980e5e5f1fb391717e0339739d2c9\Scripts\ipython-script.py:1: FutureWarning: ordered_merge is deprecated and replaced by merge_ordered
  if __name__ == '__main__':
Out[9]:
  key  lvalue group  rvalue
0   a       1     a     NaN
1   b       1     a     1.0
2   c       2     a     2.0
3   d       2     a     3.0
4   e       3     a     3.0
5   a       1     b     NaN
6   b       1     b     1.0
7   c       2     b     2.0
8   d       2     b     3.0
9   e       3     b     3.0

In [10]: pandas.merge_ordered(A, B, fill_method='ffill', left_by='group')
Out[10]:
  key  lvalue group  rvalue
0   a       1     a     NaN
1   b       1     a     1.0
2   c       2     a     2.0
3   d       2     a     3.0
4   e       3     a     3.0
5   a       1     b     NaN
6   b       1     b     1.0
7   c       2     b     2.0
8   d       2     b     3.0
9   e       3     b     3.0

Problem description

Here is the output shown in the documentation:

>>> ordered_merge(A, B, fill_method='ffill', left_by='group')
   key  lvalue group  rvalue
0    a       1     a     NaN
1    b       1     a       1
2    c       2     a       2
3    d       2     a       3
4    e       3     a       3
5    f       3     a       4
6    a       1     b     NaN
7    b       1     b       1
8    c       2     b       2
9    d       2     b       3
10   e       3     b       3
11   f       3     b       4

Note that the rows with key equal to f and rvalue equal to 4 are not present in the actual pandas output; those rows might be from an old version of the example.

Expected Output

The contents of an example are expected to be consistent with actual output from pandas, which is listed above.

Output of pd.show_versions()

[paste the output of ``pd.show_versions()`` here below this line] INSTALLED VERSIONS ------------------ commit: None python: 3.4.5.final.0 python-bits: 64 OS: Windows OS-release: 7 machine: AMD64 processor: Intel64 Family 6 Model 79 Stepping 1, GenuineIntel byteorder: little LC_ALL: None LANG: en_US.UTF-8 LOCALE: None.None pandas: 0.19.1 nose: 1.3.7 pip: 9.0.1 setuptools: 27.2.0 Cython: 0.24.1 numpy: 1.11.2 scipy: 0.18.1 statsmodels: 0.6.1 xarray: 0.8.2 IPython: 5.1.0 sphinx: 1.4.8 patsy: 0.4.1 dateutil: 2.6.0 pytz: 2016.7 blosc: 1.5.0 bottleneck: 1.2.0 tables: 3.2.2 numexpr: 2.6.1 matplotlib: 2.0.0 openpyxl: 2.4.0 xlrd: 1.0.0 xlwt: 1.1.2 xlsxwriter: 0.9.3 lxml: 3.6.4 bs4: 4.5.3 html5lib: 0.999 httplib2: 0.9.2 apiclient: None sqlalchemy: 1.1.3 pymysql: None psycopg2: 2.6.2 (dt dec pq3 ext lo64) jinja2: 2.8 boto: 2.43.0 pandas_datareader: None

Comment From: nmusolino

I am willing to create a PR with a documentation fix this weekend, if I can successfully build the documentation.

Comment From: jreback

I believe this is already fixed in master: http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.merge_ordered.html?highlight=merge_ordered#pandas.merge_ordered