Repository: pandas-dev/pandas

Issue:
DOC: Incorrect example result in 'merge_asof' docstring
Last example result  is incorrect for 'merge_asof' functon in [document](http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.merge_asof.html).

```python
>>> trades = pd.DataFrame({
...                'time': pd.to_datetime(['20160525 13:30:00.023',
...                                                     '20160525 13:30:00.038',
...                                                     '20160525 13:30:00.048',
...                                                     '20160525 13:30:00.048',
...                                                     '20160525 13:30:00.048']),
...                 'ticker': ['MSFT', 'MSFT', 'GOOG', 'GOOG', 'AAPL'],
...                 'price': [51.95, 51.95, 720.77, 720.92, 98.00],
...                 'quantity': [75, 155, 100, 100, 100]},
...                 columns=['time', 'ticker', 'price', 'quantity'])
>>> quotes = pd.DataFrame({
...                 'time': pd.to_datetime(['20160525 13:30:00.023',
...                                                      '20160525 13:30:00.023',
...                                                      '20160525 13:30:00.030',
...                                                      '20160525 13:30:00.041',
...                                                      '20160525 13:30:00.048',
...                                                      '20160525 13:30:00.049',
...                                                      '20160525 13:30:00.072',
...                                                     '20160525 13:30:00.075']),
...                   'ticker': ['GOOG', 'MSFT', 'MSFT', 'MSFT', 'GOOG', 'AAPL', 'GOOG', 'MSFT'],
...                   'bid': [720.50, 51.95, 51.97, 51.99, 720.50, 97.99, 720.50, 52.01],
...                   'ask': [720.93, 51.96, 51.98, 52.00, 720.93, 98.01, 720.88, 52.03]},
...                   columns=['time', 'ticker', 'bid', 'ask'])
```
The following changes should be made.

```python
>>> pd.merge_asof(trades, quotes,
...                       on='time',
...                       by='ticker',
...                       tolerance=pd.Timedelta('10ms'),
...                       allow_exact_matches=False)
                     time ticker   price  quantity    bid    ask
0 2016-05-25 13:30:00.023   MSFT   51.95        75    NaN    NaN
1 2016-05-25 13:30:00.038   MSFT   51.95       155  51.97  51.98
2 2016-05-25 13:30:00.048   GOOG  720.77       100    NaN    NaN
3 2016-05-25 13:30:00.048   GOOG  720.92       100    NaN    NaN
4 2016-05-25 13:30:00.048   AAPL   98.00       100    NaN    NaN
```



Discussion:
@ZhuBaohe Thanks for the report! I can confirm that this is wrong in the docs. 

PR welcome to update the docstring. Although we should also figure out if the explanation before the example is then still correct?

> We only asof within 10ms between the quote time and the trade time and we exclude exact matches on time. However prior data will propagate forward

Resolving patch:
diff --git a/pandas/core/reshape/merge.py b/pandas/core/reshape/merge.py
--- a/pandas/core/reshape/merge.py
+++ b/pandas/core/reshape/merge.py
@@ -457,8 +457,8 @@ def merge_asof(left, right, on=None,
                          time ticker   price  quantity     bid     ask
     0 2016-05-25 13:30:00.023   MSFT   51.95        75     NaN     NaN
     1 2016-05-25 13:30:00.038   MSFT   51.95       155   51.97   51.98
-    2 2016-05-25 13:30:00.048   GOOG  720.77       100  720.50  720.93
-    3 2016-05-25 13:30:00.048   GOOG  720.92       100  720.50  720.93
+    2 2016-05-25 13:30:00.048   GOOG  720.77       100     NaN     NaN
+    3 2016-05-25 13:30:00.048   GOOG  720.92       100     NaN     NaN
     4 2016-05-25 13:30:00.048   AAPL   98.00       100     NaN     NaN
 
     See also


Test patch:
diff --git a/pandas/tests/reshape/merge/test_merge_asof.py b/pandas/tests/reshape/merge/test_merge_asof.py
--- a/pandas/tests/reshape/merge/test_merge_asof.py
+++ b/pandas/tests/reshape/merge/test_merge_asof.py
@@ -92,11 +92,30 @@ def test_examples2(self):
                       by='ticker',
                       tolerance=pd.Timedelta('2ms'))
 
-        pd.merge_asof(trades, quotes,
-                      on='time',
-                      by='ticker',
-                      tolerance=pd.Timedelta('10ms'),
-                      allow_exact_matches=False)
+        expected = pd.DataFrame({
+            'time': pd.to_datetime(['20160525 13:30:00.023',
+                                    '20160525 13:30:00.038',
+                                    '20160525 13:30:00.048',
+                                    '20160525 13:30:00.048',
+                                    '20160525 13:30:00.048']),
+            'ticker': ['MSFT', 'MSFT', 'GOOG', 'GOOG', 'AAPL'],
+            'price': [51.95, 51.95,
+                      720.77, 720.92, 98.00],
+            'quantity': [75, 155,
+                         100, 100, 100],
+            'bid': [np.nan, 51.97, np.nan,
+                    np.nan, np.nan],
+            'ask': [np.nan, 51.98, np.nan,
+                    np.nan, np.nan]},
+            columns=['time', 'ticker', 'price', 'quantity',
+                     'bid', 'ask'])
+
+        result = pd.merge_asof(trades, quotes,
+                               on='time',
+                               by='ticker',
+                               tolerance=pd.Timedelta('10ms'),
+                               allow_exact_matches=False)
+        assert_frame_equal(result, expected)
 
     def test_examples3(self):
         """ doc-string examples """