|
| 1 | +--- |
| 2 | +jupyter: |
| 3 | + jupytext: |
| 4 | + notebook_metadata_filter: all |
| 5 | + text_representation: |
| 6 | + extension: .md |
| 7 | + format_name: markdown |
| 8 | + format_version: '1.2' |
| 9 | + jupytext_version: 1.3.0 |
| 10 | + kernelspec: |
| 11 | + display_name: Python 3 |
| 12 | + language: python |
| 13 | + name: python3 |
| 14 | + language_info: |
| 15 | + codemirror_mode: |
| 16 | + name: ipython |
| 17 | + version: 3 |
| 18 | + file_extension: .py |
| 19 | + mimetype: text/x-python |
| 20 | + name: python |
| 21 | + nbconvert_exporter: python |
| 22 | + pygments_lexer: ipython3 |
| 23 | + version: 3.7.3 |
| 24 | + plotly: |
| 25 | + description: How to add annotated horizontal and vertical lines in Python. |
| 26 | + display_as: file_settings |
| 27 | + language: python |
| 28 | + layout: base |
| 29 | + name: Shapes |
| 30 | + order: 37 |
| 31 | + permalink: python/horizontal-vertical-shapes/ |
| 32 | + thumbnail: thumbnail/horizontal-vertical-shapes.jpg |
| 33 | +--- |
| 34 | + |
| 35 | +### Horizontal and Vertical Lines and Boxes (Autoshapes) in Plotly.py |
| 36 | + |
| 37 | +*introduced in plotly 4.12* |
| 38 | + |
| 39 | +Horizontal and vertical lines and rectangles (autoshapes) that span an entire |
| 40 | +plot can be added via the `add_hline`, `add_vline`, `add_hrect`, and `add_vrect` |
| 41 | +methods of `plotly.graph_objects.Figure`. Shapes added with these methods are |
| 42 | +added as [layout shapes](/python/shapes) (as shown when doing `print(fig)`, for |
| 43 | +example). These shapes are fixed to the endpoints of one axis, regardless of the |
| 44 | +range of the plot, and fixed to data coordinates on the other axis. The |
| 45 | +following shows some possibilities, try panning and zooming the resulting figure |
| 46 | +to see how the shapes stick to some axes: |
| 47 | + |
| 48 | + |
| 49 | +```python |
| 50 | +import plotly.express as px |
| 51 | + |
| 52 | +df = px.data.iris() |
| 53 | +fig = px.scatter(df, x="sepal_length", y="sepal_width") |
| 54 | + |
| 55 | +# Add a vertical line that spans the entire y axis |
| 56 | +# intersecting the x axis at x=5 |
| 57 | +fig.add_vline(x=5, line_color="red") |
| 58 | +# Add a horizontal line that spans the entire x axis |
| 59 | +# intersecting the y axis at y=3 |
| 60 | +fig.add_hline(y=3, line_color="blue") |
| 61 | +# Add a vertical rectangle that spans the entire y axis |
| 62 | +# intersecting the x axis at 5.5 and 6.5 |
| 63 | +fig.add_vrect(x0=5.5, x1=6.5, line_color="purple") |
| 64 | +# Add a horizontal rectangle that spans the entire x axis |
| 65 | +# intersecting the y axis at 2.5 and 4 |
| 66 | +fig.add_hrect(y0=2.5, y1=4, line_color="orange") |
| 67 | +# (try panning and zooming the plot) |
| 68 | +fig.show() |
| 69 | +``` |
| 70 | + |
| 71 | +#### Adding Autoshapes to Multiple Facets / Subplots |
| 72 | + |
| 73 | +The same line or box can be added to multiple facets by using the `'all'` |
| 74 | +keyword in the `row` and `col` arguments like with `Figure.add_shape`. For |
| 75 | +example |
| 76 | +```python |
| 77 | +import plotly.express as px |
| 78 | + |
| 79 | +df = px.data.tips() |
| 80 | +fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex") |
| 81 | +# Adds a vertical line to all facets |
| 82 | +fig.add_vline(x=30, row="all", col="all", line_color="purple") |
| 83 | +# Adds a horizontal line to all the rows of the second column |
| 84 | +fig.add_hline(y=6, row="all", col=2, line_color="yellow") |
| 85 | +# Adds a vertical rectangle to all the columns of the first row |
| 86 | +fig.add_vrect(x0=20, x1=40, row=1, col="all", line_color="green") |
| 87 | +fig.show() |
| 88 | +``` |
| 89 | +The default `row` and `col` values are `"all"` so |
| 90 | +`fig.add_vline(x=30, line_color="purple")` is equivalent |
| 91 | +to `fig.add_vline(x=30, row="all", col="all", line_color="purple")` in the above |
| 92 | +example. |
| 93 | + |
| 94 | +#### Adding Text Annotations to Autoshapes |
| 95 | + |
| 96 | +Text [annotations](/python/text-and-annotations) can be added to an autoshape |
| 97 | +using the `annotation` keyword. Using the above example: |
| 98 | +```python |
| 99 | +import plotly.express as px |
| 100 | +import plotly.graph_objects as go |
| 101 | + |
| 102 | +df = px.data.tips() |
| 103 | +fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex") |
| 104 | +# Add annotations anchored to the top right corner of the resulting lines |
| 105 | +fig.add_vline(x=30, line_color="purple", annotation=go.layout.Annotation(text="A")) |
| 106 | +# Another way to add annotations when we are only interested in specifying text |
| 107 | +fig.add_hline(y=6, row="all", col=2, line_color="yellow", annotation_text="B") |
| 108 | +# Specify the position of the resulting annotations |
| 109 | +fig.add_vrect( |
| 110 | + x0=20, |
| 111 | + x1=40, |
| 112 | + row=1, |
| 113 | + col="all", |
| 114 | + line_color="green", |
| 115 | + annotation_text="C", |
| 116 | + annotation_position="bottom inside left", |
| 117 | +) |
| 118 | +fig.show() |
| 119 | +``` |
| 120 | +Call `help` on any of the autoshape functions in the Python interpreter to learn |
| 121 | +more (e.g., `help(fig.add_vline)`). |
0 commit comments