Figure.add_vline / add_hline mishandles the row argument, updates (n - row)th row

It appears Figure.add_vline and add_hline mishandle the row parameter for faceted / subplot figures.

Current behavior: if a facet figure has n rows, passing row=k updates row n - k. Expected behavior: passing row=k updates the kth row

import numpy as np
import pandas as pd
import plotly.express as px

rng = np.random.default_rng(0)

df = pd.DataFrame(
    {
        "A": ([1, 2, 3] * 3) * 5,
        "B": ([4] * 3 + [5] * 3 + [6] * 3) * 5,
        "C": rng.uniform(size=(45,)),
        "D": rng.uniform(size=(45,)),
    }
)

fig = px.scatter(df, x="C", y="D", facet_col="A", facet_row="B")
fig.add_hline(y=0.7, row=1, col=1)
fig.add_vline(x=0.4, row=1, col=1)
fig.update_layout(width=500, height=500)

Plotly version: v5.10.0

[nicolaskruchten]

I agree this situation is quite confusing and we should have done things differently at the outset (and TBH I can’t recall what the decision-making process was that led us here!) but unfortunately we have very little appetite for backwards-incompatible changes for these years-old APIs that thousands of charts depend on 😦

[grisaitis]

Gotcha.

I still love plotly but, respectfully, I think this is counter-intuitive and confusing. Also I think it’s such a rare scenario that, in terms of API stability, there’d be more gain than pain in changing the call to make_subplots, which I see is here (hard-coded): https://github.com/plotly/plotly.py/blob/f83921fec9492e5ec415ff14aee3c1d9b245ad99/packages/python/plotly/plotly/express/_core.py#L2366

Also I think docs should mention the behavior of start_cell in Facet and Trellis Plots in Python and Subplots in Python, where there is no discussion currently.