Merge pull request #4307 from plotly/autorange-bounds

Docs for new range and autorange options + update Plotly.js version

Author: LiamConnors

CHANGELOG.md

@@ -6,6 +6,12 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Updated
 - Improved json docstrings, added `BasePlotlyType.to_json()` method [[#4301](https://github.com/plotly/plotly.py/pull/4301)]
+- Updated Plotly.js from version 2.25.2 to version 2.26.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2260----2023-08-24) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+   - Add "min", "max", "min reversed" and "max reversed" autorange options and handle partial ranges (i.e. one end being null), add `autorangeoptions` (`clipmin`, `clipmax`, `minallowed`, `maxallowed`, `include`) as well as `minallowed` and `maxallowed` to cartesian, gl3d and radial axes [[#6547](https://github.com/plotly/plotly.js/pull/6547)]
+   - Add [n]-sigma (std deviations) box plots as an alternative to quartiles [[#6697](https://github.com/plotly/plotly.js/issues/6697)], with thanks to @28raining for the contribution!
+   - Add "top left" & "top center" side options to legend title [[#6711](https://github.com/plotly/plotly.js/pull/6711)], with thanks to @28raining for the contribution!
+   - Add "false" option to `scaleanchor` to allow removing a constraint that is set by default [[#6712](https://github.com/plotly/plotly.js/pull/6712)], with thanks to @lvlte for the contribution!
+
 
 ### Fixed
 - Fixed two issues with px.imshow: [[#4330](https://github.com/plotly/plotly.py/issues/4330)] when facet_col is an earlier dimension than animation_frame for xarrays and [[#4329](https://github.com/plotly/plotly.py/issues/4329)] when facet_col has string coordinates in xarrays [[#4331](https://github.com/plotly/plotly.py/pull/4331)]

doc/python/3d-axes.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.3'
+      jupytext_version: 1.15.1
   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.10.4
   plotly:
     description: How to format axes of 3d plots in Python with Plotly.
     display_as: 3d_charts
@@ -41,6 +41,8 @@ set the range, title, ticks, color etc. of the axes.
 
 For creating 3D charts, see [this page](https://plotly.com/python/3d-charts/).
 
+Set `range` on an axis to manually configure a range for that axis. If you don't set `range`, it's automatically calculated. In this example, we set a `range` on `xaxis`, `yaxis`, and `zaxis`.
+
 ```python
 import plotly.graph_objects as go
 import numpy as np
@@ -66,6 +68,37 @@ fig.update_layout(
 fig.show()
 ```
 
+### Setting only a Lower or Upper Bound for Range
+
+*New in 5.17*
+
+You can also set just a lower or upper bound for `range`. In this case, autorange is used for the other bound. In this example, we apply autorange to the lower bound of the `yaxis` and the upper bound of `zaxis` by setting them to `None`.
+
+```python
+import plotly.graph_objects as go
+import numpy as np
+np.random.seed(1)
+
+N = 70
+
+fig = go.Figure(data=[go.Mesh3d(x=(70*np.random.randn(N)),
+                   y=(55*np.random.randn(N)),
+                   z=(40*np.random.randn(N)),
+                   opacity=0.5,
+                   color='rgba(244,22,100,0.6)'
+                  )])
+
+fig.update_layout(
+    scene = dict(
+        xaxis = dict(nticks=4, range=[-100,100],),
+                     yaxis = dict(nticks=4, range=[None, 100],),
+                     zaxis = dict(nticks=4, range=[-100, None],),),
+    width=700,
+    margin=dict(r=20, l=10, b=10, t=10))
+
+fig.show()
+```
+
 ### Fixed Ratio Axes
 
 ```python
@@ -226,7 +259,3 @@ fig.update_layout(scene=dict(xaxis_showspikes=False,
                              yaxis_showspikes=False))
 fig.show()
 ```
-
-```python
-
-```

doc/python/axes.md

@@ -6,9 +6,9 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.1
+      jupytext_version: 1.15.1
   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.8.8
+    version: 3.10.4
   plotly:
     description: How to adjust axes properties in Python - axes titles, styling and
       coloring axes and grid lines, ticks, tick labels and more.
@@ -544,7 +544,7 @@ fig.show()
 
 #### Setting the Range of Axes Manually
 
-The visible x and y axis range can be configured manually by setting the `range` axis property to a list of two values, the lower and upper boundary.
+The visible x and y axis range can be configured manually by setting the `range` axis property to a list of two values, the lower and upper bound.
 
 Here's an example of manually specifying the x and y axis range for a faceted scatter plot created with Plotly Express.
 
@@ -559,6 +559,41 @@ fig.update_yaxes(range=[3, 9])
 fig.show()
 ```
 
+#### Setting only a Lower or Upper Bound for Range
+
+*New in 5.17*
+
+You can also set just a lower or upper bound manually and have autorange applied to the other bound by setting it to `None`. In the following example, we set a an upper bound of 4.5 on the x axes, while specifying `None` for the lower bound, meaning it will use autorange. On the y axes, we set the lower bound, and use `None` for the upper bound, meaning that uses autorange. 
+
+```python
+import plotly.express as px
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
+fig.update_xaxes(range=[None, 4.5])
+fig.update_yaxes(range=[3, None])
+
+fig.show()
+```
+
+#### Setting a Maximum and Minimum Allowed Axis Value
+
+*New in 5.17*
+
+When setting a range manually, you can also set a `maxallowed` or `minallowed` for an axis. With this set, you won't be able to pan further than the min or max allowed. In this example, we've set the minimum allowed on the x-axis to 1 and the maximum allowed on the y-axis to 10.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.update_xaxes(range=[1.5, 4.5], minallowed=1)
+fig.update_yaxes(range=[3, 9], maxallowed=10)
+
+fig.show()
+```
+
 #### Disabling Pan/Zoom on Axes (Fixed Range)
 
 Pan/Zoom can be disabled for a given axis by setting `fixedrange` to `True`.
@@ -658,37 +693,6 @@ fig.update_yaxes(
 )
 
 
-fig.show()
-```
-
-### Fixed Ratio Axes with Compressed domain
-
-If an axis needs to be compressed (either due to its own `scaleanchor` and `scaleratio` or those of the other axis), `constrain` determines how that happens: by increasing the "range" (default), or by decreasing the "domain".
-
-```python
-import plotly.graph_objects as go
-
-fig = go.Figure()
-
-fig.add_trace(go.Scatter(
-    x = [0,1,1,0,0,1,1,2,2,3,3,2,2,3],
-    y = [0,0,1,1,3,3,2,2,3,3,1,1,0,0]
-))
-
-fig.update_layout(
-    width = 800,
-    height = 500,
-    title = "fixed-ratio axes with compressed axes"
-)
-fig.update_xaxes(
-    range=[-1,4],  # sets the range of xaxis
-    constrain="domain",  # meanwhile compresses the xaxis by decreasing its "domain"
-)
-fig.update_yaxes(
-    scaleanchor = "x",
-    scaleratio = 1,
-)
-
 fig.show()
 ```
 
@@ -724,6 +728,36 @@ fig.update_yaxes(range=[9, 3])
 fig.show()
 ```
 
+*New in 5.17*
+
+To use a reversed axis while specifying only a lower bound for the range, set `autorange="min reversed"`:
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
+fig.update_yaxes(range=[9, None], autorange="min reversed")
+
+fig.show()
+```
+
+*New in 5.17*
+
+To use a reversed axis while specifying only an upper bound for the range, set `autorange="max reversed"`:
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
+fig.update_yaxes(range=[None, 3], autorange="max reversed")
+
+fig.show()
+```
+
 ### Axis range for log axis type
 
 If you are using a `log` type of axis and you want to set the range of the axis, you have to give the `log10` value of the bounds when using `fig.update_xaxes` or `fig.update_layout`. However, with `plotly.express` functions you pass directly the values of the range bounds (`plotly.express` then computes the appropriate values to pass to the figure layout).
@@ -748,25 +782,6 @@ fig.update_yaxes(type="log")
 fig.show()
 ```
 
-#### <code>nonnegative</code>, <code>tozero</code>, and <code>normal</code> Rangemode
-
-The axis auto-range calculation logic can be configured using the `rangemode` axis parameter.
-
-If `rangemode` is `"normal"` (the default), the range is computed based on the min and max values of the input data. If `"tozero"`, the range will always include zero. If `"nonnegative"`, the range will not extend below zero, regardless of the input data.
-
-Here is an example of configuring a faceted scatter plot created using Plotly Express to always include zero for both the x and y axes.
-
-```python
-import plotly.express as px
-df = px.data.iris()
-
-fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
-fig.update_xaxes(rangemode="tozero")
-fig.update_yaxes(rangemode="tozero")
-
-fig.show()
-```
-
 #### Setting the domain of the axis
 
 ```python
@@ -804,6 +819,80 @@ fig.update_xaxes(matches='x')
 fig.show()
 ```
 
+#### <code>nonnegative</code>, <code>tozero</code>, and <code>normal</code> Rangemode
+
+When you don't specify a range, autorange is used. It's also used for bounds set to `None` when providing a `range`. 
+
+The axis auto-range calculation logic can be configured using the `rangemode` axis parameter.
+
+If `rangemode` is `"normal"` (the default), the range is computed based on the min and max values of the input data. If `"tozero"`, the range will always include zero. If `"nonnegative"`, the range will not extend below zero, regardless of the input data.
+
+Here is an example of configuring a faceted scatter plot created using Plotly Express to always include zero for both the x and y axes.
+
+```python
+import plotly.express as px
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
+fig.update_xaxes(rangemode="tozero")
+fig.update_yaxes(rangemode="tozero")
+
+fig.show()
+```
+
+#### Autorange Options
+
+*New in 5.17*
+
+You can further configure how autorange is applied using `autorangeoptions` to specify maximum or minimum values or values to include.
+
+##### Specifying Minimum and Maximum Allowed Values
+
+Using `autorangeoptions.maxallowed`, you can specify an exact value to use as the autorange maximum. With `autorangeoptions.minallowed`, you can specify an exact value to use as the autorange minimum.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.update_yaxes(autorangeoptions=dict(minallowed=3))
+fig.update_xaxes(autorangeoptions=dict(maxallowed=5))
+
+fig.show()
+```
+
+##### Clip Minimum and Maximum 
+
+You can also clip an axis range at a specific maximum or minimum value with `autorangeoptions.clipmax` and `autorangeoptions.clipmin`.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.update_yaxes(autorangeoptions=dict(clipmin=5))
+fig.update_xaxes(autorangeoptions=dict(clipmax=4))
+
+fig.show()
+```
+
+##### Specify Values to be Included
+
+Use `autorangeoptions.include` to specify a value that should always be included within the calculated autorange. In this example, we specify that for the autorange calculated on the x-axis, 5 should be included. 
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length")
+fig.update_xaxes(autorangeoptions=dict(include=5))
+
+fig.show()
+```
+
 #### Reference
 
 See https://plotly.com/python/reference/layout/xaxis/ and https://plotly.com/python/reference/layout/yaxis/ for more information and chart attribute options!

packages/javascript/jupyterlab-plotly/package-lock.json

@@ -65,7 +65,7 @@
     "@lumino/messaging": "^1.2.3",
     "@lumino/widgets": "^1.8.1",
     "lodash": "^4.17.4",
-    "plotly.js": "^2.25.2"
+    "plotly.js": "^2.26.0"
   },
   "jupyterlab": {
     "extension": "lib/jupyterlab-plugin",