add_{hline,vline,hrect,vrect} and add_{shape,image,annotation} to multiple facets, squashed

.gitignore

@@ -31,7 +31,7 @@ node_modules/
 
 # virtual envs
 vv
-venv
+venv*
 
 # dist files
 build
@@ -46,4 +46,5 @@ temp-plot.html
 doc/python/.ipynb_checkpoints
 doc/python/.mapbox_token
 doc/.ipynb_checkpoints
+tags
 doc/check-or-enforce-order.py

doc/python/figure-structure.md

@@ -95,18 +95,31 @@ The third of the three top-level attributes of a figure is `frames`, whose value
 
 ### The `config` Object
 
-At [render-time](/python/renderers/), it is also possible to control certain figure behaviors which are not considered part of the figure proper i.e. the behaviour of the "modebar" and how the figure relates to mouse actions like scrolling etc. The object that contains these options is called the [`config`, and has its own documentation page](/python/configuration-options/). It is exposed in Python as the `config` keyword argument of the `.show()` method on `plotly.graph_objects.Figure` objects.
+At [render-time](/python/renderers/), it is also possible to control certain figure behaviors which are not considered part of the figure proper i.e. the behavior of the "modebar" and how the figure relates to mouse actions like scrolling etc. The object that contains these options is called the [`config`, and has its own documentation page](/python/configuration-options/). It is exposed in Python as the `config` keyword argument of the `.show()` method on `plotly.graph_objects.Figure` objects.
 
-### Positioning With Paper or Container Coordinates
+### Positioning With Paper, Container Coordinates, or Axis Domain Coordinates
 
 Various figure components configured within the layout of the figure support positioning attributes named `x` or `y`, whose values may be specified in "paper coordinates" (sometimes referred to as "plot fractions" or "normalized coordinates"). Examples include `layout.xaxis.domain` or `layout.legend.x` or `layout.annotation[].x`.
 
 Positioning in paper coordinates is *not* done in absolute pixel terms, but rather in terms relative to a coordinate system defined with an origin `(0,0)` at `(layout.margin.l, layout.margin.b)` and a point `(1,1)` at `(layout.width-layout.margin.r, layout.height-layout.margin.t)` (note: `layout.margin` values are pixel values, as are `layout.width` and `layout.height`). Paper coordinate values less than 0 or greater than 1 are permitted, and refer to areas within the plot margins.
 
+To position an object in "paper" coordinates, the corresponding axis reference
+is set to `"paper"`. For instance a shape's `xref` attribute would be set to
+`"paper"` so that the `x` value of the shape refers to its position in paper
+coordinates.
+
 Note that the contents of the `layout.margin` attribute are by default computed based on the position and dimensions of certain items like the title or legend, and may be made dependent on the position and dimensions of tick labels as well when setting the `layout.xaxis.automargin` attribute to `True`. This has the effect of automatically increasing the margin values and therefore shrinking the physical area defined between the `(0,0)` and `(1,1)` points. Positioning certain items at paper coordinates less than 0 or greater than 1 will also trigger this behavior. The `layout.width` and `layout.height`, however, are taken as givens, so a figure will never grow or shrink based on its contents.
 
 The figure title may be positioned using "container coordinates" which have `(0,0)` and `(1,1)` anchored at the bottom-left and top-right of the figure, respectively, and therefore are independent of the values of layout.margin.
 
+Furthermore, shapes, annotations, and images can be placed relative to an axis's
+domain so that, for instance, an `x` value of `0.5` would place the object
+halfway along the x-axis, regardless of the domain as specified in the
+`layout.xaxis.domain` attribute. This behavior can be specified by adding
+`' domain'` to the axis reference in the axis referencing attribute of the object.
+For example, setting `yref = 'y2 domain'` for a shape will refer to the length
+and position of the axis named `y2`.
+
 ### 2D Cartesian Trace Types and Subplots
 
 The most commonly-used kind of subplot is a [two-dimensional Cartesian subplot](/python/axes/). Traces compatible with these subplots support `xaxis` and `yaxis` attributes whose values must refer to corresponding objects in the layout portion of the figure. For example, if `xaxis="x"`, and `yaxis="y"` (which is the default) then this trace is drawn on the subplot at the intersection of the axes configured under `layout.xaxis` and `layout.yaxis`, but if `xaxis="x2"` and `yaxis="y3"` then the trace is drawn at the intersection of the axes configured under `layout.xaxis2` and `layout.yaxis3`. Note that attributes such as `layout.xaxis` and `layout.xaxis2` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of different types can be drawn on the same subplot.

doc/python/horizontal-vertical-shapes.md

@@ -0,0 +1,116 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.2'
+      jupytext_version: 1.3.0
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.7.3
+  plotly:
+    description: How to add annotated horizontal and vertical lines in Python.
+    display_as: file_settings
+    language: python
+    layout: base
+    name: Shapes
+    order: 37
+    permalink: python/horizontal-vertical-shapes/
+    thumbnail: 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
+
+
+```python
+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
+```python
+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:
+```python
+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)`).

doc/python/images.md

@@ -309,15 +309,15 @@ fig.show(config={'doubleClick': 'reset'})
 
 _introduced in plotly 4.7_
 
-It can be useful to add shapes to a layout image, for highlighting an object, drawing bounding boxes as part of a machine learning training set, or identifying seeds for a segmentation algorithm. 
+It can be useful to add shapes to a layout image, for highlighting an object, drawing bounding boxes as part of a machine learning training set, or identifying seeds for a segmentation algorithm.
 
 In order to enable shape drawing, you need to
 - define a dragmode corresponding to a drawing tool (`'drawline'`,`'drawopenpath'`, `'drawclosedpath'`, `'drawcircle'`, or `'drawrect'`)
 - add [modebar buttons](/python/configuration-options#add-optional-shapedrawing-buttons-to-modebar) corresponding to the drawing tools you wish to use.
 
 The style of new shapes is specified by the `newshape` layout attribute. Shapes can be selected and modified after they have been drawn. More details and examples are given in the [tutorial on shapes](/python/shapes#drawing-shapes-on-cartesian-plots).
 
-Drawing or modifying a shape triggers a `relayout` event, which [can be captured by a callback inside a Dash application](https://dash.plotly.com/interactive-graphing). 
+Drawing or modifying a shape triggers a `relayout` event, which [can be captured by a callback inside a Dash application](https://dash.plotly.com/interactive-graphing).
 
 ```python
 import plotly.graph_objects as go
@@ -339,7 +339,7 @@ fig.add_layout_image(
 )
 fig.update_xaxes(showgrid=False, range=(0, img_width))
 fig.update_yaxes(showgrid=False, scaleanchor='x', range=(img_height, 0))
-# Line shape added programatically 
+# Line shape added programatically
 fig.add_shape(
     type='line', xref='x', yref='y',
     x0=650, x1=1080, y0=380, y1=180, line_color='cyan'
@@ -359,5 +359,8 @@ fig.show(config={'modeBarButtonsToAdd':['drawline',
                                        ]})
 ```
 
+
+### Images Placed Relative to the Axes
+
 #### Reference
-See https://plotly.com/python/reference/layout/images/ for more information and chart attribute options!
+See https://plotly.com/python/reference/layout/images/ for more information and chart attribute options!

doc/python/shapes.md

@@ -35,7 +35,7 @@ jupyter:
 
 ### Filled Area Chart
 
-There are two ways to draw filled shapes: scatter traces and [layout.shapes](https://plotly.com/python/reference/layout/shapes/#layout-shapes-items-shape-type) which is mostly useful for the 2d subplots, and defines the shape type to be drawn, and can be rectangle, circle, line, or path (a custom SVG path). You also can use [scatterpolar](https://plotly.com/python/polar-chart/#categorical-polar-chart), scattergeo, [scattermapbox](https://plotly.com/python/filled-area-on-mapbox/#filled-scattermapbox-trace) to draw filled shapes on any kind of subplots. To set an area to be filled with a solid color, you need to define [Scatter.fill="toself"](https://plotly.com/python/reference/scatter/#scatter-fill) that connects the endpoints of the trace into a closed shape. If `mode=line` (default value), then you need to repeat the initial point of a shape at the of the sequence to have a closed shape. 
+There are two ways to draw filled shapes: scatter traces and [layout.shapes](https://plotly.com/python/reference/layout/shapes/#layout-shapes-items-shape-type) which is mostly useful for the 2d subplots, and defines the shape type to be drawn, and can be rectangle, circle, line, or path (a custom SVG path). You also can use [scatterpolar](https://plotly.com/python/polar-chart/#categorical-polar-chart), scattergeo, [scattermapbox](https://plotly.com/python/filled-area-on-mapbox/#filled-scattermapbox-trace) to draw filled shapes on any kind of subplots. To set an area to be filled with a solid color, you need to define [Scatter.fill="toself"](https://plotly.com/python/reference/scatter/#scatter-fill) that connects the endpoints of the trace into a closed shape. If `mode=line` (default value), then you need to repeat the initial point of a shape at the of the sequence to have a closed shape.
 
 ```python
 import plotly.graph_objects as go
@@ -53,7 +53,7 @@ fig = go.Figure(go.Scatter(x=[0,1,2,0,None,3,3,5,5,3], y=[0,2,0,0,None,0.5,1.5,1
 fig.show()
 ```
 
-#### Vertical and Horizontal Lines Positioned Relative to the Axes
+#### Vertical and Horizontal Lines Positioned Relative to the Axis Data
 
 ```python
 import plotly.graph_objects as go
@@ -118,7 +118,7 @@ fig.update_shapes(dict(xref='x', yref='y'))
 fig.show()
 ```
 
-#### Lines Positioned Relative to the Plot & to the Axes
+#### Lines Positioned Relative to the Plot & to the Axis Data
 
 ```python
 import plotly.graph_objects as go
@@ -227,7 +227,7 @@ fig.update_shapes(dict(
 fig.show()
 ```
 
-#### Rectangles Positioned Relative to the Axes
+#### Rectangles Positioned Relative to the Axis Data
 
 ```python
 import plotly.graph_objects as go
@@ -274,7 +274,7 @@ fig.update_shapes(dict(xref='x', yref='y'))
 fig.show()
 ```
 
-#### Rectangle Positioned Relative to the Plot & to the Axes
+#### Rectangle Positioned Relative to the Plot & to the Axis Data
 
 ```python
 import plotly.graph_objects as go
@@ -329,6 +329,38 @@ fig.add_shape(
 fig.show()
 ```
 
+#### A Rectangle Placed Relative to the Axis Position and Length
+
+A shape can be placed relative to an axis's position on the plot by adding the
+string `' domain'` to the axis reference in the `xref` or `yref` attributes for
+shapes.
+The following code places a rectangle that starts at 60% and ends at 70% along
+the x-axis, starting from the left, and starts at 80% and ends at 90% along the
+y-axis, starting from the bottom.
+
+```python
+import plotly.graph_objects as go
+import plotly.express as px
+
+df = px.data.wind()
+fig = px.scatter(df, y="frequency")
+
+fig.update_layout(xaxis=dict(domain=[0, 0.5]), yaxis=dict(domain=[0.25, 0.75]))
+
+# Add a shape whose x and y coordinates refer to the domains of the x and y axes
+fig.add_shape(
+    type="rect",
+    xref="x domain",
+    yref="y domain",
+    x0=0.6,
+    x1=0.7,
+    y0=0.8,
+    y1=0.9,
+)
+
+fig.show()
+```
+
 #### Highlighting Time Series Regions with Rectangle Shapes
 
 ```python
@@ -389,7 +421,7 @@ fig.update_layout(
 fig.show()
 ```
 
-#### Circles Positioned Relative to the Axes
+#### Circles Positioned Relative to the Axis Data
 
 ```python
 import plotly.graph_objects as go
@@ -641,7 +673,7 @@ fig.add_trace(go.Bar(x=[11,13,15], y=[8,11,20]), row=2, col=2)
 # Add shapes
 fig.update_layout(
     shapes=[
-        dict(type="line", xref="x1", yref="y1",
+        dict(type="line", xref="x", yref="y",
             x0=3, y0=0.5, x1=5, y1=0.8, line_width=3),
         dict(type="rect", xref="x2", yref='y2',
              x0=4, y0=2, x1=5, y1=6),
@@ -652,6 +684,33 @@ fig.update_layout(
 fig.show()
 ```
 
+#### Adding Shapes to Subplots
+The same shape can be added to mulitple facets by using the `'all'`
+keyword in the `row` and `col` arguments. For example
+```python
+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 rectangle to all facets
+fig.add_shape(
+    dict(type="rect", x0=25, x1=35, y0=4, y1=6, line_color="purple"),
+    row="all",
+    col="all",
+)
+# Adds a line to all the rows of the second column
+fig.add_shape(
+    dict(type="line", x0=20, x1=25, y0=5, y1=6, line_color="yellow"), row="all", col=2
+)
+
+# Adds a circle to all the columns of the first row
+fig.add_shape(
+    dict(type="circle", x0=10, y0=2, x1=20, y1=7), row=1, col="all", line_color="green"
+)
+fig.show()
+```
+
+
 #### SVG Paths
 
 ```python
@@ -724,14 +783,14 @@ You can create layout shapes programatically, but you can also draw shapes manua
 
 This shape-drawing feature is particularly interesting for annotating graphs, in particular [image traces](/python/imshow) or [layout images](/python/images).
 
-Once you have drawn shapes, you can select and modify an existing shape by clicking on its boundary (note the arrow pointer). Its fillcolor turns to pink to highlight the activated shape and then you can 
+Once you have drawn shapes, you can select and modify an existing shape by clicking on its boundary (note the arrow pointer). Its fillcolor turns to pink to highlight the activated shape and then you can
 - drag and resize it for lines, rectangles and circles/ellipses
 - drag and move individual vertices for closed paths
 - move individual vertices for open paths.
 
-An activated shape is deleted by cliking on the `eraseshape` button.
+An activated shape is deleted by clicking on the `eraseshape` button.
 
-Drawing or modifying a shape triggers a `relayout` event, which [can be captured by a callback inside a Dash application](https://dash.plotly.com/interactive-graphing). 
+Drawing or modifying a shape triggers a `relayout` event, which [can be captured by a callback inside a Dash application](https://dash.plotly.com/interactive-graphing).
 
 ```python
 import plotly.graph_objects as go
@@ -749,7 +808,7 @@ fig.add_annotation(
 # shape defined programatically
 fig.add_shape(editable=True,
               x0=-1, x1=0, y0=2, y1=3,
-              xref='x1', yref='y1')
+              xref='x', yref='y')
 # define dragmode and add modebar buttons
 fig.update_layout(dragmode='drawrect')
 fig.show(config={'modeBarButtonsToAdd':['drawline',
@@ -786,7 +845,7 @@ fig.add_shape(line_color='yellow',
               opacity=0.4,
               editable=True,
               x0=0, x1=1, y0=2, y1=3,
-              xref='x1', yref='y1'
+              xref='x', yref='y'
 )
 fig.update_layout(dragmode='drawrect',
                   # style of new shapes
@@ -803,4 +862,4 @@ fig.show(config={'modeBarButtonsToAdd':['drawline',
 ```
 
 ### Reference
-See https://plotly.com/python/reference/layout/shapes/ for more information and chart attribute options!
+See https://plotly.com/python/reference/layout/shapes/ for more information and chart attribute options!