DOC: Incorrect explanation of merge_asof with direction="backward"

[mosew]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.merge_asof.html

Documentation problem

For each row in the left DataFrame:
        A “backward” search selects the last row in the right DataFrame whose ‘on’ key is less than or equal to the left’s key.

This is incorrect, as evidenced here:

left = pd.DataFrame(
    {
        "id": ["a"],
        "date": pd.to_datetime(
            ["20080102"]
        ),
    },
)

right = pd.DataFrame(
    {
        "id": ["a"],
        "date": pd.to_datetime([
            "20080101",
        ])
    },
)

pd.merge_asof(left=left, right=right, by="id", on="date")

	id	date
	a	2008-01-02

Suggested fix for documentation

For each row in the left DataFrame:
        A “backward” search selects the last row in the **left** DataFrame whose ‘on’ key is less than or equal to the left’s key.

[mosew]

I'll add that this works fine when the left and right on names are different and one uses left_on and right_on; in that case I keep the right_on column from the result.

[j-carson]

I'm going to say, as someone who just tracked down a problem in my code due to an unexpected behavior of merge_asof direction='backward', that if the behavior is different depending on whether the column names are the same or different and whether you use on or left_on/right_on, then that's actually a bug, not a documentation issue.