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

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. 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. For example

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 dragging the plot around)
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 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)).