What is the difference between setting xref = 'paper' and xref = 'x domain' for x = 0.5?

Hello,

I am having a hard time understanding the difference between “paper” and “x domain”. I am showing two examples below. When would they be different? Thanks.

Example 1: Below are two rectangles plotted using xref = ‘paper’ & xref = ‘x domain’ and they plot exactly on top of each other.

Example 2: Below are two text annotations set to the same x value and slightly different y value to not overlap them. As seen in the graph, both start at the same x-coordinate.

@lorenpeve10

To understand the three types of refs: 1) “x”, “y”, 2) “paper”, 3) “x domain”, “y domain”, read their presentation here:
https://plotly.com/python/reference/layout/annotations/#layout-annotations-items-annotation-xref:

xref
Type: enumerated , one of ( "paper" | "/^x([2-9]|[1-9][0-9]+)?( domain)?$/" ) Sets the annotation's x coordinate axis. If set to a x axis id (e.g. "x" or "x2"), the x position refers to a x coordinate. If set to "paper", the x position refers to the distance from the left of the plotting area in normalized coordinates where "0" ("1") corresponds to the left (right). If set to a x axis ID followed by "domain" (separated by a space), the position behaves like for "paper", but refers to the distance in fractions of the domain length from the left of the domain of that axis: e.g., "x2 domain" refers to the domain of the second x axis and a x position of 0.5 refers to the point between the left and the right of the domain of the second x axis.

then look at these examples and the corresponding plots:

import plotly.graph_objects as go

fig=go.Figure(go.Scatter(x=[0,2,3], y=[0.5, -0.75, 1.63]))
fig.update_layout(width=600, height=500, xaxis_range=[-1, 4]);

fig.add_annotation(x=1,#annot placed at the point of coords(x,y)=(1,1)  with respect to axes
        y=1,
        xref="x",
        yref="y",
        text="refs 'x', 'y'<br>(1,1)",
        showarrow=False,
        align="center",
        )
fig.add_annotation(x=1, #annot places in the upper-right corner of the plot area
        y=1,
        xref="paper",
        yref="paper",
        text="refs paper<br>(1,1)",
        showarrow=False
        )
fig.add_annotation(x=1.15, #annot outside plot area (at right of it, i.e. x>1)
        y=0.4,
        xref="paper",
        yref="paper",
        text="refs paper<br>(1.15,0.4)",
        showarrow=False,
        align="right",
        xanchor="right"
        )
fig.add_annotation(x=0.5,#annot outside plot area (above it, i.e. y>1)
        y=1.2,
        xref="paper",
        yref="paper",
        text="refs paper<br>(0.5,1.2)",
        showarrow=False,
        align="right",
        )
fig.add_annotation(x=0,#annot outside plot area (below  it, i.e y<0)
        y=-0.25,
        xref="paper",
        yref="paper",
        text="refs paper<br>(0,-0.25)",
        showarrow=False,
        )
fig.update_layout(showlegend=False)
fig.show()

annots-x-paper

from plotly.subplots import make_subplots
fig1= make_subplots(rows=1, cols=2)
fig1.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 1, 3, 2, 4, 3, 4, 6, 5]
), 1, 1)
fig1.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 4, 5, 1, 2, 2, 3, 4, 2]
), 1, 2)
fig1.update_layout(width=900, height=500)

fig1.add_annotation(x=0.6,  #annot similar to ref "paper" when the fig contains only one subpl, 
                            #but here within plot area of the second trace
        y=0.75,
        xref="x2 domain",
        yref="y2 domain",
        text="refs domain<br>(0.6,0.75)",
        showarrow=False,
        align="center",
        )
fig1.add_annotation(x=0.5, #annot  with respect to "paper", below the fig plot area
        y=-0.15,
        xref="paper",
        yref="paper",
        text="refs paper<br>(0.5,-0.15)",
        showarrow=False,
        align="center",
        )
fig1.add_annotation(x=6, #annot with respect to xaxis 1, yaxis1
        y=1.5,
        xref="x1",
        yref="y1",
        text="refs x1, y1<br>(6,1.5)",
        showarrow=False,
        align="center",
        )

fig1.add_annotation(x=4, #annot with respect to xaxis2, yaxis2
        y=4.5,
        xref="x2",
        yref="y2",
        text="refs x2, y2<br>(4,4.5)",
        showarrow=False,
        align="center",
        )

1 Like

This is great! Thanks, @empet !