Documentation for 5.10 features

doc/python/box-plots.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.13.7
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.9.0
   plotly:
     description: How to make Box Plots in Python with Plotly.
     display_as: statistical
@@ -90,7 +90,7 @@ fig.show()
 
 ### Choosing The Algorithm For Computing Quartiles
 
-By default, quartiles for box plots are computed using the `linear` method (for more about linear interpolation, see #10 listed on [http://www.amstat.org/publications/jse/v14n3/langford.html](http://www.amstat.org/publications/jse/v14n3/langford.html) and [https://en.wikipedia.org/wiki/Quartile](https://en.wikipedia.org/wiki/Quartile) for more details).
+By default, quartiles for box plots are computed using the `linear` method (for more about linear interpolation, see #10 listed on [http://jse.amstat.org/v14n3/langford.html](http://jse.amstat.org/v14n3/langford.html) and [https://en.wikipedia.org/wiki/Quartile](https://en.wikipedia.org/wiki/Quartile) for more details).
 
 However, you can also choose to use an `exclusive` or an `inclusive` algorithm to compute quartiles.
 

doc/python/indicator.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.1
+      format_version: '1.3'
+      jupytext_version: 1.13.7
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.9.0
   plotly:
     description: How to make gauge charts in Python with Plotly.
     display_as: financial
@@ -61,6 +61,8 @@ In this tutorial we introduce a new trace named "Indicator". The purpose of "ind
       <li> (increasing|decreasing).symbol: symbol displayed on the left of the delta</li>
       <li> font.(family|size): to control the font</li>
       <li> position: position relative to `number` (either top, left, bottom, right)</li>
+      <li> prefix: a string to appear before the delta
+      <li> suffix: a string to appear after the delta
     </ol>
     Finally, we can have a simple title for the indicator via `title` with 'text' attribute which is a string, and 'align' which can be set to left, center, and right.
     There are two gauge types: [angular](https://plotly.com/python/gauge-charts/) and [bullet](https://plotly.com/python/bullet-charts/). Here is a combination of both shapes (angular, bullet), and different modes (gauge, delta, and value):
@@ -201,6 +203,31 @@ fig.add_trace(go.Indicator(
 fig.show()
 ```
 
+#### Adding a Prefix and Suffix
+
+
+On both a `number` and a `delta`, you can add a string to appear before the value using `prefix`. You can add a string to appear after the value using `suffix`. In the following example, we add '$' as a `prefix` and 'm' as `suffix` for both the `number` and `delta`. 
+
+Note: `suffix` and `prefix` on `delta` are new in 5.10
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Indicator(
+    mode = "number+delta",
+    value = 492,
+    number = {"prefix": "$", "suffix": "m"},
+    delta = {"reference": 512, "valueformat": ".0f", "prefix": "$", "suffix": "m"},
+    title = {"text": "Profit"},
+    domain = {'y': [0, 1], 'x': [0.25, 0.75]}))
+
+fig.add_trace(go.Scatter(
+    y = [325, 324, 405, 400, 424, 404, 417, 432, 419, 394, 410, 426, 413, 419, 404, 408, 401, 377, 368, 361, 356, 359, 375, 397, 394, 418, 437, 450, 430, 442, 424, 443, 420, 418, 423, 423, 426, 440, 437, 436, 447, 460, 478, 472, 450, 456, 436, 418, 429, 412, 429, 442, 464, 447, 434, 457, 474, 480, 499, 497, 480, 502, 512, 492]))
+
+fig.update_layout(xaxis = {'range': [0, 62]})
+fig.show()
+```
+
 #### Reference
 See https://plotly.com/python/reference/indicator/ for more information and chart attribute options!
 

doc/python/parallel-coordinates-plot.md

@@ -5,12 +5,12 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.3'
+      jupytext_version: 1.13.7
   kernel_info:
     name: python2
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -22,7 +22,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.9.0
   plotly:
     description: How to make parallel coordinates plots in Python with Plotly.
     display_as: scientific
@@ -171,6 +171,39 @@ fig = go.Figure(data=
 fig.show()
 ```
 
+### Unselected Line Color and Opacity
+
+
+*New in 5.10*
+
+The color and opacity of unselected lines can be set with `unselected`. By setting `opacity=0`, you can hide the unselected lines. Here, we set the color to `lightgray` and the opacity to `0.5`.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(data=
+    go.Parcoords(
+        line_color='blue',
+        dimensions = list([
+            dict(range = [1,5],
+                 constraintrange = [1,2], # change this range by dragging the pink line
+                 label = 'A', values = [1,4]),
+            dict(range = [1.5,5],
+                 tickvals = [1.5,3,4.5],
+                 label = 'B', values = [3,1.5]),
+            dict(range = [1,5],
+                 tickvals = [1,2,4,5],
+                 label = 'C', values = [2,4],
+                 ticktext = ['text 1', 'text 2', 'text 3', 'text 4']),
+            dict(range = [1,5],
+                 label = 'D', values = [4,2])
+        ]),
+        unselected = dict(line = dict(color = 'green', opacity = 0.5))
+    )
+)
+fig.show()
+```
+
 #### Reference
 
 See [function reference for `px.(parallel_coordinates)`](https://plotly.com/python-api-reference/generated/plotly.express.parallel_coordinates) or https://plotly.com/python/reference/parcoords/ for more information and chart attribute options!

doc/python/selections.md

@@ -0,0 +1,155 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.13.7
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    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.9.0
+  plotly:
+    description: How to use selections in Python. Examples of adding and styling selections.
+    display_as: file_settings
+    language: python
+    layout: base
+    name: Selections
+    order: 26
+    permalink: python/selections/
+    thumbnail: thumbnail/make_selection.jpg
+---
+
+## Adding Selections
+
+*New in 5.10*
+
+You can add persistent selections to a rendered figure using the **Box Select** and **Lasso Select** tools in the mode bar.
+To add multiple selections, select **Shift** when making new selections.
+To clear a selection, double-click it. On a subplot you can clear all selections by double-clicking any unselected area of the subplot.
+
+
+
+You can also add selections to a figure that displays when it renders using `fig.add_selection`.
+Here, we add a rectangular selection with a region between `3.0` and `6.5` on the x axis and between `3.5` and `5.5` on the y axis.
+
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.add_selection(x0=3.0, y0=6.5, x1=3.5, y1=5.5)
+
+fig.show()
+```
+
+## Selections Using a Custom SVG
+
+
+In the above example, we added a rectangular selection. You can also render a custom SVG for a selection by defining a `path` that can include single or multiple polygons. Here, we create a selection with a single polygon path "M2,6.5L4,7.5L4,6Z". 
+
+Please note that multiple polygons e.g. "M0,0L0,10L10,10,L10,0Z M2,2L2,8L8,8,L8,2Z" could be used to subtract certain regions from the selection.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.add_selection(path="M2,6.5L4,7.5L4,6Z")
+
+fig.show()
+```
+
+## Styling Selections
+
+
+In the above example, we added a selection to the figure that is displayed when the figure renders.
+`fig.add_selection` accepts additional properties that you can use to style the selection. Here, we add a `color`, `width`, and specify the `dash` type for the selection.
+
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.add_selection(
+    x0=2.5, y0=6.5, x1=3.5, y1=5.5,
+    line=dict(
+        color="Crimson",
+        width=2,
+        dash="dash",
+    ))
+
+fig.show()
+
+```
+
+## Fill Color for Active Selections
+
+You can style the active selection with `activeselection`. In this example, we set active selections (when created or clicked) to appear with a `fillcolor` of `yellow`.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.add_selection(x0=3.0, y0=6.5, x1=3.5, y1=5.5)
+
+fig.update_layout(dragmode='select',
+                  activeselection=dict(fillcolor='yellow'))
+
+fig.show()
+```
+
+## Styling New Selections
+
+You can style new selections made on the figure by setting properties on `newselection`.
+Try making a new selection on the figure to try it out.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+
+fig.update_layout(dragmode='select',
+                  newselection=dict(line=dict(color='blue')))
+
+fig.show()
+```
+
+## Selections with Time Series
+
+Selections are also supported on time series figures. Here, we add a rectangular selection with a region between the dates `2019-01-01"` and `"2019-10-01"` on the x axis and between `1` and `1.15` on the y axis.
+
+
+```python
+import plotly.express as px
+
+df = px.data.stocks()
+fig = px.line(df, x='date', y="GOOG")
+fig.add_selection(x0="2019-01-01", y0=1, x1="2019-10-01", y1=1.17)
+fig.show()
+```
+
+## More on Selections
+
+For more on selections, see the [selections section of the `dcc.Graph` page](https://dash.plotly.com/dash-core-components/graph#selections) in the Dash docs.

doc/python/setting-graph-size.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.6.0
+      format_version: '1.3'
+      jupytext_version: 1.13.7
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.6
+    version: 3.9.0
   plotly:
     description: How to manipulate the graph size, margins and background color.
     display_as: file_settings
@@ -127,6 +127,41 @@ fig.update_yaxes(automargin=True)
 fig.show()
 ```
 
+### Automatically Adjust Specific Margins
+
+*New in 5.10*
+
+You can also set `automargin` for specific sides of the figure. Here, we set `automargin` on the `left` and `top` of the figure.
+
+```python
+import plotly.graph_objects as go
+
+
+fig = go.Figure()
+
+fig.add_trace(go.Bar(
+    x=["Apples", "Oranges", "Watermelon", "Pears"],
+    y=[3, 2, 1, 4]
+))
+
+fig.update_layout(
+    autosize=False,
+    width=500,
+    height=500,
+    yaxis=dict(
+        title_text="Y-axis Title",
+        ticktext=["Very long label", "long label", "3", "label"],
+        tickvals=[1, 2, 3, 4],
+        tickmode="array",
+        titlefont=dict(size=30),
+    )
+)
+
+fig.update_yaxes(automargin='left+top')
+
+fig.show()
+```
+
 #### Reference
 
 See https://plotly.com/python/reference/layout/ for more information and chart attribute options!