What does overlaying parameter of layout.axis object of plotly mean?

Question

I tried to understand what this actually mean but couldn't go so far.

I play with the code below to understand it. If I delete all the overlaying parameters only the 4th will appear. If I delete one of them then only that axis is visible. I can not make any statement out of this behaviour. And no,

If set a same-letter axis id, this axis is overlaid on top of the corresponding same-letter axis, with traces and axes visible for both axes. If "False", this axis does not overlay any same-letter axes. In this case, for axes with overlapping domains only the highest-numbered axis will be visible.

the documentation also doesn't say much to me. Can anybody decrypt this explanation? Thanks.

import plotly.graph_objects as go

fig = go.Figure()

fig.add_trace(go.Scatter(
    x=[1, 2, 3],
    y=[4, 5, 6],
    name="yaxis1 data"
))


fig.add_trace(go.Scatter(
    x=[2, 3, 4],
    y=[40, 50, 60],
    name="yaxis2 data",
    yaxis="y2"
))

fig.add_trace(go.Scatter(
    x=[4, 5, 6],
    y=[40000, 50000, 60000],
    name="yaxis3 data",
    yaxis="y3"
))

fig.add_trace(go.Scatter(
    x=[5, 6, 7],
    y=[400000, 500000, 600000],
    name="yaxis4 data",
    yaxis="y4"
))


# Create axis objects
fig.update_layout(
    xaxis=dict(
        domain=[0.3, 0.7]
    ),
    yaxis=dict(
        title="yaxis title",
        titlefont=dict(
            color="#1f77b4"
        ),
        tickfont=dict(
            color="#1f77b4"
        )
    ),
    yaxis2=dict(
        title="yaxis2 title",
        titlefont=dict(
            color="#ff7f0e"
        ),
        tickfont=dict(
            color="#ff7f0e"
        ),
        anchor="free",
        overlaying="y",
        side="left",
        position=0.15
    ),
    yaxis3=dict(
        title="yaxis3 title",
        titlefont=dict(
            color="#d62728"
        ),
        tickfont=dict(
            color="#d62728"
        ),
        anchor="x",
        overlaying="y",
        side="right"
    ),
    yaxis4=dict(
        title="yaxis4 title",
        titlefont=dict(
            color="#9467bd"
        ),
        tickfont=dict(
            color="#9467bd"
        ),
        anchor="free",
        overlaying="y",
        side="right",
        position=0.85
    )
)

# Update layout properties
fig.update_layout(
    title_text="multiple y-axes example",
    width=800,
)

fig.show()

Here is the demonstration of the result when I delete all of the "overlaying" parameters. One more thing to note, I've seen multiple scatter traces being in the same plot and no mention of overlay there. I know this is related to axes but maybe I miss some fundamental knowledge about what is happening when there are multiple axes and maybe even meaning of overlaying of axes? What does it even mean? Thanks.

user_1105560 · Answer

Here's the way (I think) it works. When you create a second axis (e.g. a second y-axis), you basically create a new sub-plot that is rendered in the same place as the subplot with the first y-axis.

As a result, only the second (or last) subplot is visible. In your case, it means that when you remove the overlaying argument, you only see the last scatter - the one that is attached to y-axis #4. But - that's not what you typically want. In most cases, you'd like all the scatters, from all the overlapping subplots, to be visible at one. That's why you specify the overlaying= argument. It tells plotly not to 'hide' the lower sub-plots, but rather to make all the sub-plots except the bottom one "transparent" - as a result, all the subplots are overlayed, and visible.

Hope this helps.

There's a long discussion about the meaning of overlay here.

BTW - one may ask why not make everything overlayed, always. There's a use-case for non-overlay too:

What does overlaying parameter of layout.axis object of plotly mean?

1 Answers