Contents and sources 4 sections
Key points
- nearest can select data that arrives after a decision; this example looks ahead by 10 milliseconds.
- A backward match still needs an age limit and the correct asset identity.
- Define rules for equal timestamps and missing values; a successful join does not establish data availability.
Ten milliseconds too late is still too late
Our synthetic example places a BTC decision at 10000 milliseconds. BTC records in the right-hand table become available at 9000, 10010 and 30000 milliseconds. nearest selects 10010: only 10 milliseconds away, but later than the decision. Switching to backward selects 9000. All times are elapsed milliseconds from a shared origin; none are market observations.
The pandas documentation requires both tables to be sorted by the time key in ascending order. Here, decision_ms and available_ms retain separate decision and availability times, with by='symbol' restricting matches to the same asset. Availability should be supported by actual receipt or processing records. Renaming an exchange event timestamp cannot reconstruct transmission delay.[1]
A past record can still be too old
At the BTC decision at 20000 milliseconds, backward selects 10010. That record is 9990 milliseconds old. Adding tolerance=2000 leaves the result missing. The 2000-millisecond limit is an assumption for this demonstration, not a recommended market setting.
The same dataset includes an ETH record at 8000 milliseconds and an ETH decision at 10000. With by='symbol', the match is ETH at 8000. Removing the grouping actually selects BTC at 9000. The direction in time is correct, but the asset is wrong. Real research should identify the venue, trading pair and product type, rather than relying on an abbreviation such as BTC.
Decide what an equal timestamp permits
For the BTC decision at 30000 milliseconds, the default permits an exact match and selects the record at 30000. Keeping backward and tolerance=2000 but setting allow_exact_matches=False makes this result missing: the equal-time record is excluded and the earlier record is too old. Identical timestamps may not establish event order. The rule needs to reflect timestamp precision and processing sequence.
Retain both time columns after the join. Calculate decision_ms minus available_ms for each row and check asset identity, negative ages and expired records. Mark missing values explicitly instead of filling them with zero and treating them as observations. For revisable sources, retain the version available at the time and its acquisition timestamp. This example does not test revisions or duplicate timestamps.
Reproduce the small example
The left table contains BTC10000, ETH10000, BTC20000 and BTC30000; the right table contains ETH8000, BTC9000, BTC10010 and BTC30000. Each number is an integer millisecond value. Sort each table by time and call pd.merge_asof with left_on='decision_ms' and right_on='available_ms'. Compare nearest, backward, backward with tolerance=2000, and then exclusion of exact matches. Separately run the version without by. Change only the relevant setting each time to identify which condition changed the match.
The test ran on Windows with Python 3.14.6, pandas 3.0.1 and NumPy 2.5.4: four rows on each side, five configurations and five passing result assertions. The official 3.0-series documentation was consulted on November 5, 2026, when its page identified itself as 3.0.6; that is an access date, not a software release date. This is a data-joining tutorial. It tests no trading strategy, execution costs or slippage and cannot estimate returns. AI assisted the research, writing and editorial review. The cover is an AI concept illustration. There is no sponsorship or affiliate link, and this is not investment advice.
Sources & further reading
(1)
When checking a claim, compare the source date, measurement period and conditions. Some linked pages change over time.
For information and education, not investment advice. Crypto assets are volatile. Verify independently.
