horizontal-vertical-shapes.md

jupyter

jupytext kernelspec language_info plotly notebook_metadata_filter text_representation all extension format_name format_version jupytext_version .md markdown 1.2 1.3.0 display_name language name Python 3 python python3 codemirror_mode file_extension mimetype name nbconvert_exporter pygments_lexer version name version ipython 3 .py text/x-python python python ipython3 3.7.3 description display_as language layout name order permalink thumbnail How to add annotated horizontal and vertical lines in Python. file_settings python base Shapes 37 python/horizontal-vertical-shapes/ thumbnail/horizontal-vertical-shapes.jpg

Horizontal and Vertical Lines and Boxes (Autoshapes) in Plotly.py

introduced in plotly 4.12

Horizontal and vertical lines and rectangles (autoshapes) that span an entire plot can be added via the add_hline, add_vline, add_hrect, and add_vrect methods of plotly.graph_objects.Figure. Shapes added with these methods are added as layout shapes (as shown when doing print(fig), for example). These shapes are fixed to the endpoints of one axis, regardless of the range of the plot, and fixed to data coordinates on the other axis. The following shows some possibilities, try panning and zooming the resulting figure to see how the shapes stick to some axes:

import plotly.express as px

df = px.data.iris()
fig = px.scatter(df, x="sepal_length", y="sepal_width")

# Add a vertical line that spans the entire y axis
# intersecting the x axis at x=5
fig.add_vline(x=5, line_color="red")
# Add a horizontal line that spans the entire x axis
# intersecting the y axis at y=3
fig.add_hline(y=3, line_color="blue")
# Add a vertical rectangle that spans the entire y axis
# intersecting the x axis at 5.5 and 6.5
fig.add_vrect(x0=5.5, x1=6.5, line_color="purple")
# Add a horizontal rectangle that spans the entire x axis
# intersecting the y axis at 2.5 and 4
fig.add_hrect(y0=2.5, y1=4, line_color="orange")
# (try panning and zooming the plot)
fig.show()

Adding Autoshapes to Multiple Facets / Subplots

The same line or box can be added to multiple facets by using the 'all' keyword in the row and col arguments like with Figure.add_shape. For example

import plotly.express as px

df = px.data.tips()
fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex")
# Adds a vertical line to all facets
fig.add_vline(x=30, row="all", col="all", line_color="purple")
# Adds a horizontal line to all the rows of the second column
fig.add_hline(y=6, row="all", col=2, line_color="yellow")
# Adds a vertical rectangle to all the columns of the first row
fig.add_vrect(x0=20, x1=40, row=1, col="all", line_color="green")
fig.show()

The default row and col values are "all" so fig.add_vline(x=30, line_color="purple") is equivalent to fig.add_vline(x=30, row="all", col="all", line_color="purple") in the above example.

Adding Text Annotations to Autoshapes

Text annotations can be added to an autoshape using the annotation keyword. Using the above example:

import plotly.express as px
import plotly.graph_objects as go

df = px.data.tips()
fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex")
# Add annotations anchored to the top right corner of the resulting lines
fig.add_vline(x=30, line_color="purple", annotation=go.layout.Annotation(text="A"))
# Another way to add annotations when we are only interested in specifying text
fig.add_hline(y=6, row="all", col=2, line_color="yellow", annotation_text="B")
# Specify the position of the resulting annotations
fig.add_vrect(
    x0=20,
    x1=40,
    row=1,
    col="all",
    line_color="green",
    annotation_text="C",
    annotation_position="bottom inside left",
)
fig.show()

Call help on any of the autoshape functions in the Python interpreter to learn more (e.g., help(fig.add_vline)).