diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7eae5bb4c25..a176d1723c1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,23 +3,36 @@ All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
-## UNRELEASED
+## [5.0.0] - 2021-06-21
-### Updated
+### Updated/Changed
+
+Items in this section may be considered backwards-incompatible changes for the purposes of [Semantic Versioning](http://semver.org/) but we expect the vast majority of users to be able to upgrade to version 5.0 without encountering any issues.
-- Updated Plotly.js to version 2.0.0. See the [plotly.js 2.0.0 CHANGELOG](https://github.com/plotly/plotly.js/blob/v2.0.0/CHANGELOG.md) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
- - new `marker.pattern` options for `bar`-like trace types
- - dropped support for IE9 and IE10
- - dropped support for long-deprecated `graph_objects` like `area` traces and `scatter.(t|r)` and `layout.(radial|angular)axis` attributes
- - deprecated `heatmapgl`, `pointcloud` traces as well as all `transform` attributes
+- **Dropped support for Python older than 3.6** [#3160](https://github.com/plotly/plotly.py/pull/3160)
+- Updated Plotly.js to from version 1.58.4 to version 2.1.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#210----2021-06-18) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+ - dropped support for IE9 and IE10
+ - dropped support for long-deprecated `graph_objects` like `area` traces and `scatter.(t|r)` and `layout.(radial|angular)axis` attributes
+ - modebar no longer has `hovermode` or `showspikes` buttons by default (can be added back with `layout.modebar.add=v1hovermode`)
+ - "Aa" text no longer appears on legend items unless `mode="text"`
+ - In `bar` traces, `textposition` now defaults to `"auto"`
+ - Font size for legend and colorbar titles now matches axis title font size (slightly bigger)
+ - deprecated `heatmapgl`, `pointcloud` traces as well as all `transform` attributes
- Combined `plotlywidget` into `jupyterlab-plotly` and packaged them as a federated extension [#3142](https://github.com/plotly/plotly.py/pull/3142) with massive thanks to [@fcollonval](https://github.com/fcollonval) for the contribution
+ - In addition to this change, large Plotly.js bundles are now lazily loaded on-demand by JupyterLab
- Plotly.js CDN url will now be versioned by default for HTML exports using `include_plotlyjs='cdn'` and for "connected" renderers. [#2961](https://github.com/plotly/plotly.py/pull/2961) with thanks to [@adehad](https://github.com/adehad) for the contribution
-- Dropped support for Python older than 3.6 [#3160](https://github.com/plotly/plotly.py/pull/3160)
- Recommending Kaleido by default over Orca [#3094](https://github.com/plotly/plotly.py/pull/3094)
- Replaced `retrying` dependency with `tenacity` [#2911](https://github.com/plotly/plotly.py/pull/2911) with thanks to [@jmsmdy](https://github.com/jmsmdy) for the contribution
+- Plotly Express now always takes into account every value in `category_orders` when computing discrete mappings (color, symbol, line-dash, pattern-shapes) as well as facets, even those values which are absent in the data [#3247](https://github.com/plotly/plotly.py/pull/3247)
### Added
+- Additions due to bumping Plotly.js from 1.58.4 to 2.1.0 (see [changelog]((https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#210----2021-06-18))):
+ - New `icicle` trace type, with thanks to [@Kully](https://github.com/Kully) and [@mtwichan](https://github.com/mtwichan) of [Zyphr](https://www.zyphr.ca/) for their contribution!
+ - New `marker.pattern` options for `bar`-like trace types with thanks to [@s417-lama](https://github.com/s417-lama) for the contribution!
+ - New `legendrank` attribute to control rank of traces within legends
+- Plotly Express' `px.bar()`, `px.histogram()` and `px.bar_polar()` now support the `pattern_shape` argument [#3252](https://github.com/plotly/plotly.py/pull/3252)
+- New Plotly Express `px.icicle()` function, with thanks to [@Kully](https://github.com/Kully) and [@mtwichan](https://github.com/mtwichan) of [Zyphr](https://www.zyphr.ca/) for their contribution! [#3256](https://github.com/plotly/plotly.py/pull/3256)
- New functions in `plotly.colors`: `get_colorscale()` and `sample_colorscale()` [#3136](https://github.com/plotly/plotly.py/pull/3136) and [#3186](https://github.com/plotly/plotly.py/pull/3186) with thanks to [@CarlAndersson](https://github.com/CarlAndersson) for the contributions
- Faster JSON encoding when `orjson` is present [#2955](https://github.com/plotly/plotly.py/pull/2955)
@@ -27,6 +40,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
- Pandas and Numpy datetime serialization fixes [#3022](https://github.com/plotly/plotly.py/pull/3022)
- Fixed selected points of histograms in FigureWidget [#2771](https://github.com/plotly/plotly.py/pull/2771) with thanks to [@meffmadd](https://github.com/meffmadd) for the contribution
+- Static image export now honors `layout.(width|height)`[#3240](https://github.com/plotly/plotly.py/pull/3240)
+- Improvements to "matplotlylib" conversion utility in `plotly.tools.mpl_to_plotly()` with thanks to [@fdion](https://github.com/fdion) [#3143](https://github.com/plotly/plotly.py/pull/3143)
## [4.14.3] - 2021-01-12
diff --git a/README.md b/README.md
index dee19dd3178..9fd865ad581 100644
--- a/README.md
+++ b/README.md
@@ -37,9 +37,9 @@ Our recommended IDE for Plotly’s Python graphing library is Dash Enterprise’
## Quickstart
-`pip install plotly==4.14.3`
+`pip install plotly==5.0.0`
-Inside [Jupyter notebook](https://jupyter.org/install) (installable with `pip install "notebook>=5.3" "ipywidgets>=7.5"`):
+Inside [Jupyter](https://jupyter.org/install) (installable with `pip install "jupyterlab>=3" "ipywidgets>=7.6"`):
```python
import plotly.graph_objects as go
@@ -86,57 +86,54 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
plotly.py may be installed using pip...
```
-pip install plotly==4.14.3
+pip install plotly==5.0.0
```
or conda.
```
-conda install -c plotly plotly=4.14.3
+conda install -c plotly plotly=5.0.0
```
-### Jupyter Notebook Support
+### JupyterLab Support
-For use in the Jupyter Notebook, install the `notebook` and `ipywidgets`
+For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
packages using `pip`:
```
-pip install "notebook>=5.3" "ipywidgets>=7.5"
+$ pip install "jupyterlab>=3" "ipywidgets>=7.6"
```
or `conda`:
```
-conda install "notebook>=5.3" "ipywidgets>=7.5"
+$ conda install "jupyterlab>=3" "ipywidgets>=7.6"
```
-### JupyterLab Support
-
-For use in JupyterLab, install the `jupyterlab` and `ipywidgets`
-packages using `pip`:
+The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**, run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
```
-pip install jupyterlab "ipywidgets>=7.5"
+# JupyterLab 2.x renderer support
+jupyter labextension install jupyterlab-plotly@5.0.0 @jupyter-widgets/jupyterlab-manager
```
-or `conda`:
+Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.
+
+### Jupyter Notebook Support
+
+For use in the Jupyter Notebook, install the `notebook` and `ipywidgets`
+packages using `pip`:
```
-conda install jupyterlab "ipywidgets>=7.5"
+pip install "notebook>=5.3" "ipywidgets>=7.5"
```
-Then run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
+or `conda`:
```
-# Basic JupyterLab renderer support
-jupyter labextension install jupyterlab-plotly@4.14.3
-
-# OPTIONAL: Jupyter widgets extension for FigureWidget support
-jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.14.3
+conda install "notebook>=5.3" "ipywidgets>=7.5"
```
-Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.
-
### Static Image Export
plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
diff --git a/doc/python/aggregations.md b/doc/python/aggregations.md
index ccd0aeb36a8..b171bf6ca5c 100644
--- a/doc/python/aggregations.md
+++ b/doc/python/aggregations.md
@@ -33,6 +33,8 @@ jupyter:
thumbnail: thumbnail/aggregations.jpg
---
+> **Note** `transforms` are deprecated in `plotly` v5 and will be removed in a future version.
+
#### Introduction
Aggregates are a type of transform that can be applied to values in a given expression. Available aggregations are:
diff --git a/doc/python/bar-charts.md b/doc/python/bar-charts.md
index 948628392fa..f02892d6da9 100644
--- a/doc/python/bar-charts.md
+++ b/doc/python/bar-charts.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -47,7 +47,7 @@ fig.show()
```
-#### Bar chart with Long Format Data
+#### Bar charts with Long Format Data
Long-form data has one row per observation, and one column per variable. This is suitable for storing and displaying multivariate data i.e. with dimension greater than 2. This format is sometimes called "tidy".
@@ -69,7 +69,7 @@ fig.show()
long_df
```
-#### Bar chart with Wide Format Data
+#### Bar charts with Wide Format Data
Wide-form data has one row per value of one of the first variable, and one column per value of the second variable. This is suitable for storing and displaying 2-dimensional data.
```python
@@ -85,7 +85,7 @@ fig.show()
wide_df
```
-### Bar chart in Dash
+### Bar charts in Dash
[Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
@@ -98,9 +98,9 @@ snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
IFrame(snippet_url + 'bar-charts', width='100%', height=630)
```
-### Customize bar chart with Plotly Express
+### Customize bar charts with Plotly Express
-The bar plot can be customized using keyword arguments.
+The bar plot can be customized using keyword arguments, for example to use [continuous color](https://plotly.com/python/colorscales/), as below, or [discrete color](/python/discrete-color/), as above.
```python
import plotly.express as px
@@ -122,8 +122,9 @@ fig = px.bar(df, x="sex", y="total_bill", color='time')
fig.show()
```
+The default stacked bar chart behavior can be changed to grouped (also known as clustered) using the `barmode` argument:
+
```python
-# Change the default stacking
import plotly.express as px
df = px.data.tips()
fig = px.bar(df, x="sex", y="total_bill",
@@ -132,6 +133,20 @@ fig = px.bar(df, x="sex", y="total_bill",
fig.show()
```
+*New in v5.0*
+
+
+Bar charts afford the use of [patterns (also known as hatching or texture)](/python/pattern-hatching-texture/) in addition to color:
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation",
+ pattern_shape="nation", pattern_shape_sequence=[".", "x", "+"])
+fig.show()
+```
+
#### Facetted subplots
Use the keyword arguments `facet_row` (resp. `facet_col`) to create facetted subplots, where different rows (resp. columns) correspond to different values of the dataframe column specified in `facet_row`.
@@ -335,8 +350,8 @@ for key in data:
])
))
-fig.update_xaxes(
- tickvals=np.cumsum(widths)-widths/2,
+fig.update_xaxes(
+ tickvals=np.cumsum(widths)-widths/2,
ticktext= ["%s
%d" % (l, w) for l, w in zip(labels, widths)]
)
diff --git a/doc/python/compare-webgl-svg.md b/doc/python/compare-webgl-svg.md
deleted file mode 100644
index 934dfa7a7de..00000000000
--- a/doc/python/compare-webgl-svg.md
+++ /dev/null
@@ -1,105 +0,0 @@
----
-jupyter:
- jupytext:
- notebook_metadata_filter: all
- text_representation:
- extension: .md
- format_name: markdown
- format_version: '1.1'
- jupytext_version: 1.1.7
- 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.6.5
- plotly:
- description: Comparing WebGL with Scattergl() to SVG with Scatter() in Python
- with Plotly.
- has_thumbnail: false
- language: python
- layout: base
- name: Comparing WebGL vs SVG
- page_type: example_index
- permalink: python/compare-webgl-svg/
- thumbnail: /images/static-image
----
-
-### Comparing Scatter Plots with 75,000 Random Points
-
-
-Now in Plotly you can implement WebGL with `Scattergl()` in place of `Scatter()`
-for increased speed, improved interactivity, and the ability to plot even more data!
-
-
-### WebGL
-
-```python
-import plotly.graph_objects as go
-
-import numpy as np
-np.random.seed(1)
-
-N = 75000
-
-fig = go.Figure()
-fig.add_trace(
- go.Scattergl(
- x = np.random.randn(N),
- y = np.random.randn(N),
- mode = 'markers',
- marker = dict(
- line = dict(
- width = 1,
- color = 'DarkSlateGrey')
- )
- )
-)
-
-fig.update_layout(title_text = 'WebGL')
-
-fig.show()
-```
-
-### SVG
-
-```python
-import plotly.graph_objects as go
-
-import numpy as np
-
-N = 75000
-
-fig = go.Figure()
-fig.add_trace(
- go.Scatter(
- x = np.random.randn(N),
- y = np.random.randn(N),
- mode = 'markers',
- marker = dict(
- line = dict(
- width = 1,
- color = 'DarkSlateGrey')
- )
- )
-)
-
-fig.update_layout(title_text = 'SVG')
-
-fig.show()
-```
-
-### References
-
-
-For more information see
-`Scattergl()` : https://plotly.com/python/reference/scattergl/
-`Scatter()` : https://plotly.com/python/reference/scatter/
diff --git a/doc/python/configuration-options.md b/doc/python/configuration-options.md
index 62fe7d51664..f0590762fef 100644
--- a/doc/python/configuration-options.md
+++ b/doc/python/configuration-options.md
@@ -63,18 +63,20 @@ fig.add_trace(
fig.show(config=config)
```
-### Forcing The Modebar to Always Be Visible
+### Turning Off Responsiveness
-When users hover over a figure generated with plotly.py, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure.
+By default, figures you create with the `plotly.py` package are [responsive](https://en.wikipedia.org/wiki/Responsive_web_design). Responsive figures automatically change their height and width when the size of the window they are displayed in changes. This is true for figures which are displayed in web browsers on desktops and mobile, Jupyter Notebooks, and other [rendering](https://plot.ly/python/renderers/) environments.
-By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to always be visible regardless of whether or not the user is currently hovering over the figure, set the displayModeBar attribute in the configuration of your figure to true.
+Try resizing your browser window to see this behavior in effect on this page.
+
+If you would like to disable this default behavior and force your figures to always have the same height and width regardless of the window size, set the value of the `responsive` key to `False` in your figure's configuration dictionary.
```python
import plotly.graph_objects as go
fig = go.Figure()
-config = {'displayModeBar': True}
+config = {'responsive': False}
fig.add_trace(
go.Scatter(
@@ -84,18 +86,14 @@ fig.add_trace(
fig.show(config=config)
```
-### Preventing the Modebar from Appearing
-
-When users hover over a figure generated with `plotly.py`, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure.
-
-By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to never be visible, then set the `displayModeBar` attribute in the config of your figure to false.
+### Making A Static Chart
```python
import plotly.graph_objects as go
fig = go.Figure()
-config = {'displayModeBar': False}
+config = {'staticPlot': True}
fig.add_trace(
go.Scatter(
@@ -105,15 +103,18 @@ fig.add_trace(
fig.show(config=config)
```
+### Forcing The Modebar to Always Be Visible
-### Hiding the Plotly Logo on the Modebar
+When users hover over a figure generated with plotly.py, a **modebar** appears in the top-right of the figure. This presents users with several options for interacting with the figure.
+
+By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to always be visible regardless of whether or not the user is currently hovering over the figure, set the displayModeBar attribute in the configuration of your figure to true.
```python
import plotly.graph_objects as go
fig = go.Figure()
-config = {'displaylogo': False}
+config = {'displayModeBar': True}
fig.add_trace(
go.Scatter(
@@ -123,20 +124,18 @@ fig.add_trace(
fig.show(config=config)
```
-### Turning Off Responsiveness
-
-By default, figures you create with the `plotly.py` package are [responsive](https://en.wikipedia.org/wiki/Responsive_web_design). Responsive figures automatically change their height and width when the size of the window they are displayed in changes. This is true for figures which are displayed in web browsers on desktops and mobile, Jupyter Notebooks, and other [rendering](https://plot.ly/python/renderers/) environments.
+### Preventing the Modebar from Appearing
-Try resizing your browser window to see this behavior in effect on this page.
+When users hover over a figure generated with `plotly.py`, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure.
-If you would like to disable this default behavior and force your figures to always have the same height and width regardless of the window size, set the value of the `responsive` key to `False` in your figure's configuration dictionary.
+By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to never be visible, then set the `displayModeBar` attribute in the config of your figure to false.
```python
import plotly.graph_objects as go
fig = go.Figure()
-config = {'responsive': False}
+config = {'displayModeBar': False}
fig.add_trace(
go.Scatter(
@@ -146,14 +145,15 @@ fig.add_trace(
fig.show(config=config)
```
-### Making A Static Chart
+
+### Hiding the Plotly Logo on the Modebar
```python
import plotly.graph_objects as go
fig = go.Figure()
-config = {'staticPlot': True}
+config = {'displaylogo': False}
fig.add_trace(
go.Scatter(
@@ -163,7 +163,7 @@ fig.add_trace(
fig.show(config=config)
```
-### Customizing Download Plot Button Options
+### Customizing Modebar "Download Plot" Button
The camera icon on the modebar causes a static version of the figure to be downloaded via the user's browser. The default behaviour is to download a PNG of size 700 by 450 pixels.
@@ -202,38 +202,36 @@ fig = px.bar(x=[1, 2, 3], y=[1, 3, 1])
fig.show(config=config)
```
-### Specifying Multiple Configuration Options Simultaneously
+### Removing Modebar Buttons
-The dictionary that you use to specify configuration options for your figures can contain more than one configuration key/value pair.
+To delete buttons from the modebar, pass an array of strings containing the names of the buttons you want to remove to the `modeBarButtonsToRemove` attribute in the figure's configuration dictionary. Note that different chart types have different default modebars. The following is a list of all the modebar buttons and the chart types they are associated with:
+
+ - **High-level**: `zoom`, `pan`, `select`, `zoomIn`, `zoomOut`, `autoScale`, `resetScale`
+ - **2D**: `zoom2d`, `pan2d`, `select2d`, `lasso2d`, `zoomIn2d`, `zoomOut2d`, `autoScale2d`, `resetScale2d`
+ - **2D Shape Drawing**: `drawline`, `drawopenpath`, `drawclosedpath`, `drawcircle`, `drawrect`, `eraseshape`
+ - **3D**: `zoom3d`, `pan3d`, `orbitRotation`, `tableRotation`, `handleDrag3d`, `resetCameraDefault3d`, `resetCameraLastSave3d`, `hoverClosest3d`
+ - **Cartesian**: `hoverClosestCartesian`, `hoverCompareCartesian`
+ - **Geo**: `zoomInGeo`, `zoomOutGeo`, `resetGeo`, `hoverClosestGeo`
+ - **Other**: `hoverClosestGl2d`, `hoverClosestPie`, `toggleHover`, `resetViews`, `toImage`, `sendDataToCloud`, `toggleSpikelines`, `resetViewMapbox`
```python
import plotly.graph_objects as go
fig = go.Figure()
-config = dict({
- 'scrollZoom': True,
- 'displayModeBar': True,
- 'editable': True
-})
-
fig.add_trace(
go.Scatter(
x=[1, 2, 3],
y=[1, 3, 1]))
-fig.show(config=config)
+fig.show(config={
+ 'modeBarButtonsToRemove': ['zoom', 'pan']
+})
```
-### Removing Modebar Buttons
+*New in v5.0*
-To delete buttons from the modebar, pass an array of strings containing the names of the buttons you want to remove to the `modeBarButtonsToRemove` attribute in the figure's configuration dictionary. Note that different chart types have different default modebars. The following is a list of all the modebar buttons and the chart types they are associated with:
-
- - **2D**: `zoom2d`, `pan2d`, `select2d`, `lasso2d`, `zoomIn2d`, `zoomOut2d`, `autoScale2d`, `resetScale2d`
- - **3D**: `zoom3d`, `pan3d`, `orbitRotation`, `tableRotation`, `handleDrag3d`, `resetCameraDefault3d`, `resetCameraLastSave3d`, `hoverClosest3d`
- - **Cartesian**: `hoverClosestCartesian`, `hoverCompareCartesian`
- - **Geo**: `zoomInGeo`, `zoomOutGeo`, `resetGeo`, `hoverClosestGeo`
- - **Other**: `hoverClosestGl2d`, `hoverClosestPie`, `toggleHover`, `resetViews`, `toImage: sendDataToCloud`, `toggleSpikelines`, `resetViewMapbox`
+The `layout.modebar.remove` attribute can be used instead of the approach used above:
```python
import plotly.graph_objects as go
@@ -245,13 +243,13 @@ fig.add_trace(
x=[1, 2, 3],
y=[1, 3, 1]))
-fig.show(config={
- 'modeBarButtonsToRemove': ['toggleSpikelines','hoverCompareCartesian']
-})
+fig.update_layout(modebar_remove=['zoom', 'pan'])
```
### Add optional shape-drawing buttons to modebar
+*New in v4.7*
+
Some modebar buttons of Cartesian plots are optional and have to be added explicitly, using the `modeBarButtonsToAdd` config attribute. These buttons are used for drawing or erasing shapes. See [the tutorial on shapes and shape drawing](python/shapes#drawing-shapes-on-cartesian-plots) for more details.
```python
@@ -273,6 +271,29 @@ fig.show(config={'modeBarButtonsToAdd':['drawline',
]})
```
+*New in v5.0*
+
+The `layout.modebar.add` attribute can be used instead of the approach used above:
+
+```python
+import plotly.graph_objects as go
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x='petal_width', y='sepal_length', color='species')
+fig.update_layout(
+ dragmode='drawopenpath',
+ newshape_line_color='cyan',
+ title_text='Draw a path to separate versicolor and virginica',
+ modebar_add=['drawline',
+ 'drawopenpath',
+ 'drawclosedpath',
+ 'drawcircle',
+ 'drawrect',
+ 'eraseshape'
+ ]
+)
+```
+
### Double-Click Delay
Sets the maximum delay between two consecutive clicks to be interpreted as a double-click in milliseconds. This is the time interval between first mousedown and second mouseup. The default timing is 300 ms (less than half a second).
This setting propagates to all on-subplot double clicks (except for `geo` and `mapbox`).
diff --git a/doc/python/filter.md b/doc/python/filter.md
index d3fb6a86886..9a75ec79d68 100644
--- a/doc/python/filter.md
+++ b/doc/python/filter.md
@@ -33,6 +33,8 @@ jupyter:
thumbnail: thumbnail/filter.jpg
---
+> **Note** `transforms` are deprecated in `plotly` v5 and will be removed in a future version
+
#### Basic Example
```python
diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md
index f74baab2ca1..d9f93fd11b4 100644
--- a/doc/python/getting-started.md
+++ b/doc/python/getting-started.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -34,7 +34,6 @@ jupyter:
- /python/pytables/
---
-
### Overview
@@ -72,7 +71,6 @@ This package contains everything you need to write figures to standalone HTML fi
> Note: **No internet connection, account, or payment is required to use plotly.py.** Prior to version 4, this library could operate in either an "online" or "offline" mode. The documentation tended to emphasize the online mode, where graphs get published to the Chart Studio web service. In version 4, all "online" functionality was removed from the `plotly` package and is now available as the separate, optional, `chart-studio` package (See below). **plotly.py version 4 is "offline" only, and does not include any functionality for uploading figures or data to cloud services.**
-
```python
import plotly.graph_objects as go
@@ -93,32 +91,28 @@ snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
IFrame(snippet_url + 'getting-started', width='100%', height=630)
```
-
-
-#### Jupyter Notebook Support
+#### JupyterLab Support
-For use in the classic [Jupyter Notebook](https://jupyter.org/), install the `notebook` and `ipywidgets`
+For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
packages using `pip`:
```
-$ pip install "notebook>=5.3" "ipywidgets>=7.5"
+$ pip install "jupyterlab>=3" "ipywidgets>=7.6"
```
or `conda`:
```
-$ conda install "notebook>=5.3" "ipywidgets>=7.5"
+$ conda install "jupyterlab>=3" "ipywidgets>=7.6"
```
-These packages contain everything you need to run a Jupyter notebook...
+These packages contain everything you need to run JupyterLab...
```
-$ jupyter notebook
+$ jupyter lab
```
-and display plotly figures inline using the notebook renderer...
-
-
+and display plotly figures inline using the `plotly_mimetype` renderer...
```python
import plotly.graph_objects as go
@@ -134,44 +128,43 @@ fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig
```
-
+The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**, run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
+
+```
+# JupyterLab 2.x renderer support
+jupyter labextension install jupyterlab-plotly@4.14.3 @jupyter-widgets/jupyterlab-manager
+```
+
+Please check out our [Troubleshooting guide](/python/troubleshooting/) if you run into any problems with JupyterLab, particularly if you are using multiple python environments inside Jupyter.
+
See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.
-#### JupyterLab Support
-For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
-packages using `pip`:
-```
-$ pip install jupyterlab "ipywidgets>=7.6"
-```
+#### Jupyter Notebook Support
-or `conda`:
+For use in the classic [Jupyter Notebook](https://jupyter.org/), install the `notebook` and `ipywidgets`
+packages using `pip`:
```
-$ conda install jupyterlab "ipywidgets>=7.6"
+$ pip install "notebook>=5.3" "ipywidgets>=7.5"
```
-For JupyterLab 2 or earlier, run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
+or `conda`:
```
-# JupyterLab renderer support
-jupyter labextension install jupyterlab-plotly@4.14.3
-
-# OPTIONAL: Jupyter widgets extension
-jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.14.3
+$ conda install "notebook>=5.3" "ipywidgets>=7.5"
```
-These packages contain everything you need to run JupyterLab...
+These packages contain everything you need to run a Jupyter notebook...
```
-$ jupyter lab
+$ jupyter notebook
```
-and display plotly figures inline using the `plotly_mimetype` renderer...
+and display plotly figures inline using the notebook renderer...
-
```python
import plotly.graph_objects as go
@@ -179,7 +172,7 @@ fig = go.Figure(data=go.Bar(y=[2, 3, 1]))
fig.show()
```
-or using `FigureWidget` objects (if the "OPTIONAL" step above was executed).
+or using `FigureWidget` objects.
```python
import plotly.graph_objects as go
@@ -187,12 +180,9 @@ fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig
```
-Please check out our [Troubleshooting guide](/python/troubleshooting/) if you run into any problems with JupyterLab, particularly if you are using multiple python environments inside Jupyter.
-
-
-
See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.
+
### Static Image Export
plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
@@ -283,5 +273,3 @@ Once you've installed, you can use our documentation in three main ways:
For information on using Python to build web applications containing plotly figures, see the [_Dash User Guide_](https://dash.plotly.com/).
We also encourage you to join the [Plotly Community Forum](http://community.plotly.com/) if you want help with anything related to `plotly`.
-
-
diff --git a/doc/python/group-by.md b/doc/python/group-by.md
index ac9d1464523..ce9b0d7a2c8 100644
--- a/doc/python/group-by.md
+++ b/doc/python/group-by.md
@@ -33,6 +33,8 @@ jupyter:
thumbnail: thumbnail/groupby.jpg
---
+> **Note** `transforms` are deprecated in `plotly` v5 and will be removed in a future version.
+
#### Basic Example
```python
diff --git a/doc/python/histograms.md b/doc/python/histograms.md
index 0f0d0a001ca..214e61d45b5 100644
--- a/doc/python/histograms.md
+++ b/doc/python/histograms.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.6
+ version: 3.7.7
plotly:
description: How to make Histograms in Python with Plotly.
display_as: statistical
@@ -36,12 +36,12 @@ jupyter:
thumbnail: thumbnail/histogram.jpg
---
-In statistics, a [histogram](https://en.wikipedia.org/wiki/Histogram) is representation of the distribution of numerical data, where the data are binned and the count for each bin is represented. More generally, in plotly a histogram is an aggregated bar chart, with several possible aggregation functions (e.g. sum, average, count...). Also, the data to be binned can be numerical data but also categorical or date data.
+In statistics, a [histogram](https://en.wikipedia.org/wiki/Histogram) is representation of the distribution of numerical data, where the data are binned and the count for each bin is represented. More generally, in plotly a histogram is an aggregated bar chart, with several possible aggregation functions (e.g. sum, average, count...).
-If you're looking instead for bar charts, i.e. representing data with rectangular
+If you're looking instead for bar charts, i.e. representing *raw, unaggregated* data with rectangular
bar, go to the [Bar Chart tutorial](/python/bar-charts/).
-## Histogram with Plotly Express
+## Histograms with Plotly Express
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
@@ -71,6 +71,30 @@ fig = px.histogram(df, x="total_bill", nbins=20)
fig.show()
```
+### Histograms on Date Data
+
+Plotly histograms will automatically bin date data in addition to numerical data:
+
+```python
+import plotly.express as px
+
+df = px.data.stocks()
+fig = px.histogram(df, x="date")
+fig.update_layout(bargap=0.2)
+fig.show()
+```
+
+### Histograms on Categorical Data
+
+Plotly histograms will automatically bin numerical or date data but can also be used on raw categorical data, as in the following example, where the X-axis value is the categorical "day" variable:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.histogram(df, x="day", category_orders=dict(day=["Thur", "Fri", "Sat", "Sun"]))
+fig.show()
+```
+
#### Histograms in Dash
[Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
@@ -147,6 +171,26 @@ fig = px.histogram(df, x="total_bill", y="tip", histfunc='avg')
fig.show()
```
+The default `histfunc` is `sum` if `y` is given, and works with categorical as well as binned numeric data on the `x` axis:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.histogram(df, x="day", y="total_bill", category_orders=dict(day=["Thur", "Fri", "Sat", "Sun"]))
+fig.show()
+```
+*New in v5.0*
+
+Histograms afford the use of [patterns (also known as hatching or texture)](/python/pattern-hatching-texture/) in addition to color:
+
+```python
+import plotly.express as px
+
+df = px.data.tips()
+fig = px.histogram(df, x="sex", y="total_bill", color="sex", pattern_shape="smoker")
+fig.show()
+```
+
#### Visualizing the distribution
With the `marginal` keyword, a subplot is drawn alongside the histogram, visualizing the distribution. See [the distplot page](https://plotly.com/python/distplot/)for more examples of combined statistical representations.
diff --git a/doc/python/hover-text-and-formatting.md b/doc/python/hover-text-and-formatting.md
index 6ff3db3205e..8d6381b1dc3 100644
--- a/doc/python/hover-text-and-formatting.md
+++ b/doc/python/hover-text-and-formatting.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.6
+ version: 3.7.7
plotly:
description: How to use hover text and formatting in Python with Plotly.
display_as: file_settings
@@ -248,9 +248,43 @@ print("user_defined hovertemplate:", fig.data[0].hovertemplate)
fig.show()
```
+### Hover Templates with Mixtures of Period data
+
+*New in v5.0*
+
+When [displaying periodic data](https://plotly.com/python/time-series/#displaying-period-data) with mixed-sized periods (i.e. quarterly and monthly) in conjunction with `x` or `x unified` hovermodes and using `hovertemplate`, the `xhoverformat` attribute can be used to control how each period's X value is displayed, and the special `%{xother}` hover-template directive can be used to control how the X value is displayed for points that do not share the exact X coordinate with the point that is being hovered on. `%{xother}` will return an empty string when the X value is the one being hovered on, otherwise it will return `(%{x})`. The special `%{_xother}`, `%{xother_}` and `%{_xother_}` variations will display with spaces before, after or around the parentheses, respectively.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Bar(
+ x=["2020-01-01", "2020-04-01", "2020-07-01"],
+ y=[1000, 1500, 1700],
+ xperiod="M3",
+ xperiodalignment="middle",
+ xhoverformat="Q%q",
+ hovertemplate="%{y}%{_xother}"
+))
+
+fig.add_trace(go.Scatter(
+ x=["2020-01-01", "2020-02-01", "2020-03-01",
+ "2020-04-01", "2020-05-01", "2020-06-01",
+ "2020-07-01", "2020-08-01", "2020-09-01"],
+ y=[1100,1050,1200,1300,1400,1700,1500,1400,1600],
+ xperiod="M1",
+ xperiodalignment="middle",
+ hovertemplate="%{y}%{_xother}"
+))
+
+fig.update_layout(hovermode="x unified")
+fig.show()
+```
+
### Advanced Hover Template
-The following example shows how to format hover template. [Here](https://plotly.com/python/v3/hover-text-and-formatting/#dash-example) is an example to see how to format hovertemplate in Dash.
+The following example shows how to format a hover template.
```python
import plotly.graph_objects as go
diff --git a/doc/python/icicle-charts.md b/doc/python/icicle-charts.md
index 61577f641d3..8ff9688ca06 100644
--- a/doc/python/icicle-charts.md
+++ b/doc/python/icicle-charts.md
@@ -33,13 +33,9 @@ jupyter:
thumbnail: thumbnail/icicle.png
---
-Icicle charts visualize hierarchical data using rectangular sectors that cascade from root to leaves in one of four directions: up, down, left, or right. Similar to [Sunburst](https://plotly.com/python/sunburst-charts/) and [Treemap](https://plotly.com/python/treemaps/) charts, the hierarchy is defined by `labels` (`names` for `px.icicle`) and `parents` attributes. Click on one sector to zoom in/out, which also displays a pathbar on the top of your icicle. To zoom out, you can click the parent sector or click the pathbar as well.
+*New in v5.0*
-Main arguments:
-
-1. `labels` (`names` in `px.icicle` since `labels` is reserved for overriding columns names): sets the labels of icicle sectors.
-2. `parents`: sets the parent sectors of icicle sectors. An empty string `''` is used for the root node in the hierarchy. In this example, the root is "Eve".
-3. `values`: sets the values associated with icicle sectors, determining their width (See the `branchvalues` section below for different modes for setting the width).
+Icicle charts visualize hierarchical data using rectangular sectors that cascade from root to leaves in one of four directions: up, down, left, or right. Similar to [Sunburst charts](https://plotly.com/python/sunburst-charts/) and [Treemaps](https://plotly.com/python/treemaps/) charts, the hierarchy is defined by `labels` (`names` for `px.icicle`) and `parents` attributes. Click on one sector to zoom in/out, which also displays a pathbar on the top of your icicle. To zoom out, you can click the parent sector or click the pathbar as well.
### Basic Icicle Plot with plotly.express
@@ -60,6 +56,8 @@ fig =px.icicle(
parents='parent',
values='value',
)
+fig.update_traces(root_color="lightgrey")
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -71,7 +69,9 @@ Hierarchical data are often stored as a rectangular dataframe, with different co
```python
import plotly.express as px
df = px.data.tips()
-fig = px.icicle(df, path=['day', 'time', 'sex'], values='total_bill')
+fig = px.icicle(df, path=[px.Constant("all"), 'day', 'time', 'sex'], values='total_bill')
+fig.update_traces(root_color="lightgrey")
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -83,10 +83,11 @@ If a color argument is passed, the color of a node is computed as the average of
import plotly.express as px
import numpy as np
df = px.data.gapminder().query("year == 2007")
-fig = px.icicle(df, path=['continent', 'country'], values='pop',
+fig = px.icicle(df, path=[px.Constant("world"), 'continent', 'country'], values='pop',
color='lifeExp', hover_data=['iso_alpha'],
color_continuous_scale='RdBu',
color_continuous_midpoint=np.average(df['lifeExp'], weights=df['pop']))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -97,7 +98,9 @@ When the argument of color corresponds to non-numerical data, discrete colors ar
```python
import plotly.express as px
df = px.data.tips()
-fig = px.icicle(df, path=['sex', 'day', 'time'], values='total_bill', color='day')
+fig = px.icicle(df, path=[px.Constant("all"), 'sex', 'day', 'time'],
+ values='total_bill', color='day')
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -106,7 +109,9 @@ In the example below the color of **Saturday** and **Sunday** sectors is the sam
```python
import plotly.express as px
df = px.data.tips()
-fig = px.icicle(df, path=['sex', 'day', 'time'], values='total_bill', color='time')
+fig = px.icicle(df, path=[px.Constant("all"), 'sex', 'day', 'time'],
+ values='total_bill', color='time')
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -117,8 +122,10 @@ For more information about discrete colors, see the [dedicated page](https://plo
```python
import plotly.express as px
df = px.data.tips()
-fig = px.icicle(df, path=['sex', 'day', 'time'], values='total_bill', color='time',
- color_discrete_map={'(?)':'black', 'Lunch':'gold', 'Dinner':'darkblue'})
+fig = px.icicle(df, path=[px.Constant("all"), 'sex', 'day', 'time'],
+ values='total_bill', color='time',
+ color_discrete_map={'(?)':'lightgrey', 'Lunch':'gold', 'Dinner':'darkblue'})
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -138,8 +145,11 @@ sales = [1, 3, 2, 4, 1, 2, 2, 1, 4, 1]
df = pd.DataFrame(
dict(vendors=vendors, sectors=sectors, regions=regions, sales=sales)
)
+df["all"] = "all" # in order to have a single root node
print(df)
-fig = px.icicle(df, path=['regions', 'sectors', 'vendors'], values='sales')
+fig = px.icicle(df, path=['all', 'regions', 'sectors', 'vendors'], values='sales')
+fig.update_traces(root_color='lightgrey')
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -147,6 +157,12 @@ fig.show()
If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Icicle` class from `plotly.graph_objects`](/python/graph-objects/).
+Main arguments:
+
+1. `labels` (`names` in `px.icicle` since `labels` is reserved for overriding columns names): sets the labels of icicle sectors.
+2. `parents`: sets the parent sectors of icicle sectors. An empty string `''` is used for the root node in the hierarchy. In this example, the root is "Eve".
+3. `values`: sets the values associated with icicle sectors, determining their width (See the `branchvalues` section below for different modes for setting the width).
+
```python
import plotly.graph_objects as go
@@ -154,11 +170,10 @@ fig =go.Figure(go.Icicle(
labels=["Eve", "Cain", "Seth", "Enos", "Noam", "Abel", "Awan", "Enoch", "Azura"],
parents=["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve" ],
values=[10, 14, 12, 10, 2, 6, 6, 4, 4],
+ root_color="lightgrey"
))
-# Update layout for tight margin
-# See https://plotly.com/python/creating-and-updating-figures/
-fig.update_layout(margin = dict(t=0, l=0, r=0, b=0))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -168,27 +183,28 @@ fig.show()
import plotly.graph_objects as go
fig =go.Figure(go.Icicle(
- ids=[
+ ids=["Sports",
"North America", "Europe", "Australia", "North America - Football", "Soccer",
"North America - Rugby", "Europe - Football", "Rugby",
"Europe - American Football","Australia - Football", "Association",
"Australian Rules", "Autstralia - American Football", "Australia - Rugby",
"Rugby League", "Rugby Union"
],
- labels= [
+ labels= ["Sports",
"North
America", "Europe", "Australia", "Football", "Soccer", "Rugby",
"Football", "Rugby", "American
Football", "Football", "Association",
"Australian
Rules", "American
Football", "Rugby", "Rugby
League",
"Rugby
Union"
],
- parents=[
- "", "", "", "North America", "North America", "North America", "Europe",
+ parents=["",
+ "Sports", "Sports", "Sports", "North America", "North America", "North America", "Europe",
"Europe", "Europe","Australia", "Australia - Football", "Australia - Football",
"Australia - Football", "Australia - Football", "Australia - Rugby",
"Australia - Rugby"
],
+ root_color="lightgrey"
))
-fig.update_layout(margin = dict(t=0, l=0, r=0, b=0))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -207,8 +223,9 @@ fig =go.Figure(go.Icicle(
parents=["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve" ],
values=[ 65, 14, 12, 10, 2, 6, 6, 4, 4],
branchvalues="total",
+ root_color="lightgrey"
))
-fig.update_layout(margin = dict(t=0, l=0, r=0, b=0))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -222,30 +239,18 @@ import plotly.graph_objects as go
import pandas as pd
-df1 = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
-df2 = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/coffee-flavors.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
fig = go.Figure()
fig.add_trace(go.Icicle(
- ids=df1.ids,
- labels=df1.labels,
- parents=df1.parents,
- domain=dict(column=0)
-))
-
-fig.add_trace(go.Icicle(
- ids=df2.ids,
- labels=df2.labels,
- parents=df2.parents,
- domain=dict(column=1),
- maxdepth=2
+ ids=df.ids,
+ labels=df.labels,
+ parents=df.parents,
+ root_color="lightgrey"
))
-fig.update_layout(
- grid= dict(columns=2, rows=1),
- margin = dict(t=0, l=0, r=0, b=0)
-)
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -254,17 +259,24 @@ fig.show()
If you want all the text labels to have the same size, you can use the `uniformtext` layout parameter. The `minsize` attribute sets the font size, and the `mode` attribute sets what happens for labels which cannot fit with the desired fontsize: either `hide` them or `show` them with overflow.
+*Note: animated transitions are currently not implemented when `uniformtext` is used.*
+
```python
import plotly.graph_objects as go
import pandas as pd
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
fig = go.Figure(go.Icicle(
- ids = df.ids,
- labels = df.labels,
- parents = df.parents))
-fig.update_layout(uniformtext=dict(minsize=10, mode='hide'))
+ ids = df.ids,
+ labels = df.labels,
+ parents = df.parents,
+ root_color="lightgrey"
+))
+fig.update_layout(
+ uniformtext=dict(minsize=10, mode='hide'),
+ margin = dict(t=50, l=25, r=25, b=25)
+)
fig.show()
```
@@ -344,7 +356,7 @@ fig.add_trace(go.Icicle(
maxdepth=2
), 1, 2)
-fig.update_layout(margin=dict(t=10, b=10, r=10, l=10))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -353,14 +365,16 @@ fig.show()
```python
import plotly.graph_objects as go
-labels = ["A1", "A2", "A3", "A4", "A5", "B1", "B2"]
-parents = ["", "A1", "A2", "A3", "A4", "", "B1"]
+labels = ["container", "A1", "A2", "A3", "A4", "A5", "B1", "B2"]
+parents = ["", "container", "A1", "A2", "A3", "A4", "container", "B1"]
fig = go.Figure(go.Icicle(
labels = labels,
parents = parents,
- marker_colors = ["pink", "royalblue", "lightgray", "purple", "cyan", "lightgray", "lightblue"]))
+ marker_colors = ["pink", "royalblue", "lightgray", "purple",
+ "cyan", "lightgray", "lightblue", "lightgreen"]))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -369,31 +383,37 @@ This example uses iciclecolorway attribute, which should be set in layout.
```python
import plotly.graph_objects as go
-labels = ["A1", "A2", "A3", "A4", "A5", "B1", "B2"]
-parents = ["", "A1", "A2", "A3", "A4", "", "B1"]
+values = [0, 11, 12, 13, 14, 15, 20, 30]
+labels = ["container", "A1", "A2", "A3", "A4", "A5", "B1", "B2"]
+parents = ["", "container", "A1", "A2", "A3", "A4", "container", "B1"]
fig = go.Figure(go.Icicle(
labels = labels,
- parents = parents
+ parents = parents,
+ values=values,
+ root_color="lightblue"
))
-fig.update_layout(iciclecolorway = ["pink", "lightgray"])
-
+fig.update_layout(
+ iciclecolorway = ["pink", "lightgray"],
+ margin = dict(t=50, l=25, r=25, b=25)
+)
fig.show()
```
```python
import plotly.graph_objects as go
-values = ["11", "12", "13", "14", "15", "20", "30"]
-labels = ["A1", "A2", "A3", "A4", "A5", "B1", "B2"]
-parents = ["", "A1", "A2", "A3", "A4", "", "B1"]
+values = [0, 11, 12, 13, 14, 15, 20, 30]
+labels = ["container", "A1", "A2", "A3", "A4", "A5", "B1", "B2"]
+parents = ["", "container", "A1", "A2", "A3", "A4", "container", "B1"]
fig = go.Figure(go.Icicle(
labels = labels,
values = values,
parents = parents,
marker_colorscale = 'Blues'))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -402,56 +422,50 @@ fig.show()
As mentioned above, Icicle charts can grow in one of four directions. Icicle charts have a `tiling` attribute and this has two attributes: `orientation` and `flip`. `orientation` takes either `h` (horiztonal) or `v` (vertical) and `flip` takes either `x` or `y`. You can use these two attributes in combination to create each of the four cardinal directions: left, right, top, bottom.
-NB. A "flame chart" refers to an Icicle chart that is pointing upwards.
-
-**Up Direction**
+**Up Direction (Flame Chart)**
```python
import plotly.graph_objects as go
import pandas as pd
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
fig = go.Figure(
go.Icicle(
ids = df.ids,
labels = df.labels,
parents = df.parents,
+ root_color="lightgrey",
tiling = dict(
orientation='v',
flip='y'
)
)
)
-
-fig.update_layout(
- margin = {'t':0, 'l':0, 'r':0, 'b':0}
-)
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
-**Down Direction**
+**Down Direction (Icicle)**
```python
import plotly.graph_objects as go
import pandas as pd
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
fig = go.Figure(
go.Icicle(
ids = df.ids,
labels = df.labels,
parents = df.parents,
+ root_color="lightgrey",
tiling = dict(
orientation='v'
)
)
)
-
-fig.update_layout(
- margin = {'t':0, 'l':0, 'r':0, 'b':0}
-)
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -461,22 +475,20 @@ fig.show()
import plotly.graph_objects as go
import pandas as pd
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
fig = go.Figure(
go.Icicle(
ids = df.ids,
labels = df.labels,
parents = df.parents,
+ root_color="lightgrey",
tiling = dict(
orientation='h'
)
)
)
-
-fig.update_layout(
- margin = {'t':0, 'l':0, 'r':0, 'b':0}
-)
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -486,119 +498,24 @@ fig.show()
import plotly.graph_objects as go
import pandas as pd
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
fig = go.Figure(
go.Icicle(
ids = df.ids,
labels = df.labels,
parents = df.parents,
+ root_color="lightgrey",
tiling = dict(
orientation='h',
flip='x'
)
)
)
-
-fig.update_layout(
- margin = {'t':0, 'l':0, 'r':0, 'b':0}
-)
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
-### Pad
-
-Similar to [treemaps](https://plotly.com/python/treemaps/), the space between each Icicle slice can be set with `pad`, one of the sub-attributes of the `tiling` attribute.
-
-
-```python
-import plotly.graph_objs as go
-from plotly.subplots import make_subplots
-import pandas as pd
-
-df1 = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
-
-pad_values = [0, 2, 4, 6]
-num_of_cols = 4
-
-fig = make_subplots(
- rows = 1, cols = 4,
- column_titles=[f'pad: {pad_values[i]}' for i in range(num_of_cols)],
- specs = [
- [
- dict(type = 'icicle', rowspan = 1) for i in range(num_of_cols)
- ]
- ]
-)
-
-fig.add_trace(
- go.Icicle(
- ids = df1.ids,
- labels = df1.labels,
- parents = df1.parents,
- pathbar = dict(side = 'bottom'),
- root = dict(color = 'DodgerBlue'),
- tiling = dict(
- pad = pad_values[0]
- )
- ),
- col = 1,
- row = 1
-)
-
-fig.add_trace(
- go.Icicle(
- ids = df1.ids,
- labels = df1.labels,
- parents = df1.parents,
- pathbar = dict(side = 'bottom'),
- root = dict(color = 'DodgerBlue'),
- tiling = dict(
- pad = pad_values[1]
- )
- ),
- col = 2,
- row = 1
-)
-
-fig.add_trace(
- go.Icicle(
- ids = df1.ids,
- labels = df1.labels,
- parents = df1.parents,
- pathbar = dict(side = 'bottom'),
- root = dict(color = 'DodgerBlue'),
- tiling = dict(
- pad = pad_values[2]
- )
- ),
- col = 3,
- row = 1
-)
-
-fig.add_trace(
- go.Icicle(
- ids = df1.ids,
- labels = df1.labels,
- parents = df1.parents,
- pathbar = dict(side = 'bottom'),
- root = dict(color = 'DodgerBlue'),
- tiling = dict(
- pad = pad_values[3]
- )
- ),
- col = 4,
- row = 1
-)
-
-fig.update_layout(
- margin = dict(l=0, r=0)
-)
-
-fig.show()
-```
-
-
#### Reference
See [function reference for `px.icicle()`](https://plotly.com/python-api-reference/generated/plotly.express.icicle) or https://plotly.com/python/reference/icicle/ for more information and chart attribute options!
diff --git a/doc/python/legend.md b/doc/python/legend.md
index f576ab73dab..ed240829b7d 100644
--- a/doc/python/legend.md
+++ b/doc/python/legend.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.6
+ version: 3.7.7
plotly:
description: How to configure and style the legend in Plotly with Python.
display_as: file_settings
@@ -97,6 +97,23 @@ fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1]))
fig.show()
```
+*New in v5.0*
+
+The `legendrank` attribute of a trace can be used to control its placement within the legend, without regard for its placement in the `data` list.
+
+The default `legendrank` for traces is 1000 and ties are broken as described above, meaning that any trace can be pulled up to the top if it is the only one with a legend rank less than 1000 and pushed to the bottom if it is the only one with a rank greater than 1000.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1], legendrank=4))
+fig.add_trace(go.Bar(name="second", x=["a", "b"], y=[2,1], legendrank=2))
+fig.add_trace(go.Bar(name="first", x=["a", "b"], y=[1,2], legendrank=1))
+fig.add_trace(go.Bar(name="third", x=["a", "b"], y=[1,2], legendrank=3))
+fig.show()
+```
+
#### Showing and Hiding the Legend
By default the legend is displayed on Plotly charts with multiple traces, and this can be explicitly set with the `layout.showlegend` attribute:
diff --git a/doc/python/multiple-transforms.md b/doc/python/multiple-transforms.md
index b41f322f2ea..83dcde464a3 100644
--- a/doc/python/multiple-transforms.md
+++ b/doc/python/multiple-transforms.md
@@ -34,6 +34,8 @@ jupyter:
thumbnail: thumbnail/multiple-transforms.jpg
---
+> **Note** `transforms` are deprecated in `plotly` v5 and will be removed in a future version.
+>
#### Filter and Group By
```python
diff --git a/doc/python/pattern-hatching-texture.md b/doc/python/pattern-hatching-texture.md
new file mode 100644
index 00000000000..b2059069cda
--- /dev/null
+++ b/doc/python/pattern-hatching-texture.md
@@ -0,0 +1,147 @@
+---
+jupyter:
+ jupytext:
+ notebook_metadata_filter: all
+ text_representation:
+ extension: .md
+ format_name: markdown
+ format_version: '1.2'
+ jupytext_version: 1.4.2
+ 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.7
+ plotly:
+ description: How to use patterns (also known as hatching or texture) with bar
+ charts.
+ display_as: basic
+ language: python
+ layout: base
+ name: Patterns, Hatching, Texture
+ order: 18
+ page_type: u-guide
+ permalink: python/pattern-hatching-texture/
+ thumbnail: thumbnail/pattern.png
+---
+
+*New in v5.0*
+
+[Bar charts](/python/bar-charts/), [histograms](/python/histograms/) and [polar bar charts](/python/wind-rose-charts/) have large markers which support not only a fill color, but also an optional **pattern** (also known as "hatching" or "texture"). This can be used for a variety of reasons:
+
+* to double-encode variables (i.e. using both color and pattern) to improve accessibility for visually-impaired end-users
+* to encode an additional variable beyond just using color
+* to make charts that are easier to print in black and white
+
+
+### Patterned Bar Charts with Plotly Express
+
+the `px.bar()`, `px.histogram()` and `px.bar_polar()` functions support the `pattern_shape` argument. In the chart below, we double-encode `nation` using color and pattern:
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation", pattern_shape="nation")
+fig.show()
+```
+
+In the chart below we use `px.histogram()` instead of `px.bar()` to aggregate multiple values together, and encode one variable (sex) using both color and x-position and another (smoker) using patterns:
+
+```python
+import plotly.express as px
+
+df = px.data.tips()
+fig = px.histogram(df, x="sex", y="total_bill", color="sex", pattern_shape="smoker")
+fig.show()
+```
+
+### Controlling Pattern Assignment
+
+In the charts above, the first value of the variable assigned `pattern_shape` gets the empty pattern, but this (and indeed every pattern-to-variable assignment) can be controlled using `pattern_shape_sequence` and `pattern_shape_map`, analogously to the way [discrete colors](/python/discrete-color/) can be mapped using Plotly Express.
+
+Here we use `pattern_shape_sequence` to replace the defaults and include a pattern-shape for the first variable:
+
+```python tags=[]
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation",
+ pattern_shape="nation", pattern_shape_sequence=[".", "x", "+"])
+fig.show()
+```
+
+Here we use `pattern_shape_map` to explictly assign a shape to each value of `nation`, regardless of order:
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation",
+ pattern_shape="nation", pattern_shape_map={
+ "China": ".", "Canada": "/", "South Korea": "+"
+ })
+fig.show()
+```
+
+### Black on White Patterns for Print
+
+When creating figures meant to be printed on black and white printers, it is better to *replace* the fill-color with the pattern, rather than to overlay it. This can be controlled with the `.marker.pattern.fillmode` attribute, which defaults to `"overlay"` but can be set to `"replace"` instead. Changing this attribute, and using a simpler default template and color scheme gives the following output:
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation",
+ pattern_shape="nation", pattern_shape_sequence=[".", "x", "+"],
+ template="simple_white"
+ )
+fig.update_traces(
+ marker=dict(color="black", line_color="black", pattern_fillmode="replace")
+)
+fig.show()
+```
+
+Of course, this setting can be used without making the figure monochrome as well:
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation",
+ pattern_shape="nation", pattern_shape_sequence=[".", "x", "+"],
+ )
+fig.update_traces(
+ marker=dict(line_color="grey", pattern_fillmode="replace")
+)
+fig.show()
+```
+
+### Patterns using Graph Objects
+
+If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Bar` class from `plotly.graph_objects`](/python/graph-objects/).
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Bar(x=["a","b"], y=[1,2], marker_pattern_shape="."))
+fig.add_trace(go.Bar(x=["a","b"], y=[3,1], marker_pattern_shape="x"))
+fig.add_trace(go.Bar(x=["a","b"], y=[2,3], marker_pattern_shape="+"))
+
+fig.show()
+```
+
+#### Reference
+
+See https://plotly.com/python/reference/bar/ for more information and chart attribute options!
diff --git a/doc/python/plotly-express.md b/doc/python/plotly-express.md
index 60a88e98590..2238c5ead0e 100644
--- a/doc/python/plotly-express.md
+++ b/doc/python/plotly-express.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -130,6 +130,15 @@ fig = px.bar(df, x="sex", y="total_bill", color="smoker", barmode="group")
fig.show()
```
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation",
+ pattern_shape="nation", pattern_shape_sequence=[".", "x", "+"])
+fig.show()
+```
+
**Read more about [facet plots](/python/facet-plots/).**
```python
@@ -243,6 +252,17 @@ fig = px.treemap(df, path=[px.Constant('world'), 'continent', 'country'], values
fig.show()
```
+**Read more about [treemaps](/python/icicle-charts/).**
+
+```python
+import plotly.express as px
+import numpy as np
+df = px.data.gapminder().query("year == 2007")
+fig = px.icicle(df, path=[px.Constant('world'), 'continent', 'country'], values='pop',
+ color='lifeExp', hover_data=['iso_alpha'])
+fig.show()
+```
+
#### Distributions
**Read more about [histograms](/python/histograms/).**
diff --git a/doc/python/renderers.md b/doc/python/renderers.md
index d7e0f0748f1..cdc1cf98197 100644
--- a/doc/python/renderers.md
+++ b/doc/python/renderers.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.6
+ version: 3.7.7
plotly:
description: Displaying Figures using Plotly's Python graphing library
display_as: file_settings
@@ -38,15 +38,17 @@ jupyter:
Plotly's Python graphing library, `plotly.py`, gives you a wide range of options for how and where to display your figures.
-In general, there are three different approaches you can take in order to display figures:
+In general, there are five different approaches you can take in order to display `plotly` figures:
- 1. Using the renderers framework in the context of a script or notebook
+ 1. Using the `renderers` framework in the context of a script or notebook (the main topic of this page)
2. Using [Dash](https://dash.plot.ly) in a web app context
- 3. Using a `FigureWidget` in an `ipywidgets` context
+ 3. Using a [`FigureWidget` rather than a `Figure`](https://plotly.com/python/figurewidget/) in an [`ipywidgets` context](https://ipywidgets.readthedocs.io/en/stable/)
+ 4. By [exporting to an HTML file](https://plotly.com/python/interactive-html-export/) and loading that file in a browser immediately or later
+ 5. By [rendering the figure to a static image file using Kaleido](https://plotly.com/python/static-image-export/) such as PNG, JPEG, SVG, PDF or EPS and loading the resulting file in any viewer
-Each of these approaches is discussed below.
+Each of the first three approaches is discussed below.
-### Displaying Figures Using The renderers Framework
+### Displaying Figures Using The `renderers` Framework
The renderers framework is a flexible approach for displaying `plotly.py` figures in a variety of contexts. To display a figure using the renderers framework, you call the `.show()` method on a graph object figure, or pass the figure to the `plotly.io.show` function. With either approach, `plotly.py` will display the figure using the current default renderer(s).
@@ -72,7 +74,7 @@ fig
> To be precise, figures will display themselves using the current default renderer when the two following conditions are true. First, the last expression in a cell must evaluate to a figure. Second, `plotly.py` must be running from within an `IPython` kernel.
-**In many contexts, an appropriate renderer will be chosen automatically and you will not need to perform any additional configuration.** These contexts include the classic [Jupyter Notebook](https://jupyter.org/), [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) (provided the `plotlywidget` JupyterLab extension is installed), [Visual Studio Code notebooks](https://code.visualstudio.com/docs/python/jupyter-support), [Google Colaboratory](https://colab.research.google.com/notebooks/intro.ipynb), [Kaggle](https://www.kaggle.com/kernels) notebooks, [Azure](https://notebooks.azure.com/) notebooks, and the [Python interactive shell](https://www.python.org/shell/).
+**In many contexts, an appropriate renderer will be chosen automatically and you will not need to perform any additional configuration.** These contexts include the classic [Jupyter Notebook](https://jupyter.org/), [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), [Visual Studio Code notebooks](https://code.visualstudio.com/docs/python/jupyter-support), [Google Colaboratory](https://colab.research.google.com/notebooks/intro.ipynb), [Kaggle](https://www.kaggle.com/kernels) notebooks, [Azure](https://notebooks.azure.com/) notebooks, and the [Python interactive shell](https://www.python.org/shell/).
Additional contexts are supported by choosing a compatible renderer including the [IPython console](https://docs.spyder-ide.org/ipythonconsole.html), [QtConsole](https://qtconsole.readthedocs.io/en/stable/), [Spyder](https://www.spyder-ide.org/), and more.
@@ -81,19 +83,6 @@ Next, we will show how to configure the default renderer. After that, we will d
> Note: The `renderers` framework is a generalization of the `plotly.offline.iplot` and `plotly.offline.plot` functions that were the recommended way to display figures prior to `plotly.py` version 4. These functions have been reimplemented using the `renderers` framework and are still supported for backward compatibility, but they will not be discussed here.
-### Displaying figures in Dash
-
-[Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
-
-Get started with [the official Dash docs](https://dash.plotly.com/installation) and **learn how to effortlessly [style](https://plotly.com/dash/design-kit/) & [deploy](https://plotly.com/dash/app-manager/) apps like this with Dash Enterprise.**
-
-
-```python hide_code=true
-from IPython.display import IFrame
-snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
-IFrame(snippet_url + 'renderers', width='100%', height=630)
-```
-
#### Setting The Default Renderer
The current and available renderers are configured using the `plotly.io.renderers` configuration object. Display this object to see the current default renderer and the list of all available renderers.
@@ -169,7 +158,7 @@ This renderer may be useful when working with notebooks than contain lots of lar
###### `plotly_mimetype`
-The `plotly_mimetype` renderer creates a specification of the figure (called a MIME-type bundle), and requests that the current user interface displays it. User interfaces that support this renderer include [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) (requires the [`plotlywidget`](https://www.npmjs.com/package/plotlywidget) extension), [nteract](https://nteract.io/), and the Visual Studio Code [notebook interface](https://code.visualstudio.com/docs/python/jupyter-support).
+The `plotly_mimetype` renderer creates a specification of the figure (called a MIME-type bundle), and requests that the current user interface displays it. User interfaces that support this renderer include [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), [nteract](https://nteract.io/), and the Visual Studio Code [notebook interface](https://code.visualstudio.com/docs/python/jupyter-support).
###### `jupyterlab`, `nteract`, and `vscode`
These are aliases for `plotly_mimetype` since this renderer is a good choice when working in JupyterLab, nteract, and the Visual Studio Code notebook interface. Note that in VSCode Notebooks, the version of Plotly.js that is used to render is provided by the [vscode-python extension](https://code.visualstudio.com/docs/languages/python) and often trails the latest version by several weeks, so the latest features of `plotly` may not be available in VSCode right away. The situation is similar for Nteract.
@@ -241,9 +230,33 @@ fig = go.Figure(
fig.show(renderer="png", width=800, height=300)
```
+### Displaying figures in Dash
+
+[Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
+
+Get started with [the official Dash docs](https://dash.plotly.com/installation) and **learn how to effortlessly [style](https://plotly.com/dash/design-kit/) & [deploy](https://plotly.com/dash/app-manager/) apps like this with Dash Enterprise.**
+
+
+```python hide_code=true
+from IPython.display import IFrame
+snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
+IFrame(snippet_url + 'renderers', width='100%', height=630)
+```
+
## Displaying Figures Using `ipywidgets`
Plotly figures can be displayed in [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) contexts using `plotly.graph_objects.FigureWidget` objects. `FigureWidget` is a figure graph object (just like `plotly.graph_objects.Figure`), so you can add traces to it and update it just like a regular `Figure`. But `FigureWidget` is also an `ipywidgets` object, which means that you can display it alongside other `ipywidgets` to build user interfaces right in the notebook.
See the [Plotly FigureWidget Overview](https://plot.ly/python/figurewidget/) for more information on integrating `plotly.py` figures with `ipywidgets`.
It is important to note that `FigureWidget` does not use the renderers framework discussed above, so you should not use the `show()` figure method or the `plotly.io.show` function on `FigureWidget` objects.
+
+
+## Performance
+
+No matter the approach chosen to display a figure, [the figure data structure](https://plotly.com/python/figure-structure/) is first (automatically, internally) serialized into a JSON string before being transferred from the Python context to the browser (or [to an HTML file first](https://plotly.com/python/interactive-html-export/) or [to Kaleido for static image export](https://plotly.com/python/static-image-export/)).
+
+*New in v5.0*
+
+The default JSON serialization mechanism can be slow for figures with many data points or with large `numpy` arrays or data frames. **If [the `orjson` package](https://github.com/ijl/orjson) is installed**, `plotly` will use that instead of the built-in `json` package, which can lead to **5-10x** speedups for large figures.
+
+Once a figure is serialized to JSON, it must be rendered by a browser, either immediately in the user's browser, at some later point if the figure is exported to HTML, or immediately in Kaleido's internal headless browser for static image export. Rendering time is generally proportional to the total number of data points in the figure, the number of traces and the number of subplots. In situations where rendering performance is slow, we recommend considering [the use of `plotly` WebGL traces](/python/webgl-vs-svg/) to exploit GPU-accelerated rendering in the browser, or [using the Datashader library to do Python-side rendering](/python/datashader/) before using `px.imshow()` to render the figure.
diff --git a/doc/python/sunburst-charts.md b/doc/python/sunburst-charts.md
index 44c696e170b..249dde5783a 100644
--- a/doc/python/sunburst-charts.md
+++ b/doc/python/sunburst-charts.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.3.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.3
+ version: 3.7.7
plotly:
description: How to make Sunburst Charts.
display_as: basic
@@ -33,13 +33,7 @@ jupyter:
thumbnail: thumbnail/sunburst.gif
---
-Sunburst plots visualize hierarchical data spanning outwards radially from root to leaves. The sunburst sector hierarchy is determined by the entries in `labels` (`names` in `px.sunburst`) and in `parents`. The root starts from the center and children are added to the outer rings.
-
-Main arguments:
-
-1. `labels` (`names` in `px.sunburst` since `labels` is reserved for overriding columns names): sets the labels of sunburst sectors.
-2. `parents`: sets the parent sectors of sunburst sectors. An empty string `''` is used for the root node in the hierarchy. In this example, the root is "Eve".
-3. `values`: sets the values associated with sunburst sectors, determining their width (See the `branchvalues` section below for different modes for setting the width).
+Sunburst plots visualize hierarchical data spanning outwards radially from root to leaves. Similar to [Icicle charts](https://plotly.com/python/icicle-charts/) and [Treemaps](https://plotly.com/python/treemaps/), the hierarchy is defined by `labels` (`names` for `px.icicle`) and `parents` attributes. The root starts from the center and children are added to the outer rings.
### Basic Sunburst Plot with plotly.express
@@ -146,6 +140,12 @@ fig.show()
If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Sunburst` class from `plotly.graph_objects`](/python/graph-objects/).
+Main arguments:
+
+1. `labels` (`names` in `px.sunburst` since `labels` is reserved for overriding columns names): sets the labels of sunburst sectors.
+2. `parents`: sets the parent sectors of sunburst sectors. An empty string `''` is used for the root node in the hierarchy. In this example, the root is "Eve".
+3. `values`: sets the values associated with sunburst sectors, determining their width (See the `branchvalues` section below for different modes for setting the width).
+
```python
import plotly.graph_objects as go
@@ -284,6 +284,8 @@ fig.show()
If you want all the text labels to have the same size, you can use the `uniformtext` layout parameter. The `minsize` attribute sets the font size, and the `mode` attribute sets what happens for labels which cannot fit with the desired fontsize: either `hide` them or `show` them with overflow.
+*Note: animated transitions are currently not implemented when `uniformtext` is used.*
+
```python
import plotly.graph_objects as go
import pandas as pd
diff --git a/doc/python/time-series.md b/doc/python/time-series.md
index 7e5883e8938..38f59dcf2e3 100644
--- a/doc/python/time-series.md
+++ b/doc/python/time-series.md
@@ -203,9 +203,45 @@ fig.update_xaxes(showgrid=True, ticklabelmode="period")
fig.show()
```
+### Hover Templates with Mixtures of Period data
+
+*New in v5.0*
+
+When displaying periodic data with mixed-sized periods (i.e. quarterly and monthly) in conjunction with [`x` or `x unified` hovermodes and using `hovertemplate`](https://plotly.com/python/hover-text-and-formatting/), the `xhoverformat` attribute can be used to control how each period's X value is displayed, and the special `%{xother}` hover-template directive can be used to control how the X value is displayed for points that do not share the exact X coordinate with the point that is being hovered on. `%{xother}` will return an empty string when the X value is the one being hovered on, otherwise it will return `(%{x})`. The special `%{_xother}`, `%{xother_}` and `%{_xother_}` variations will display with spaces before, after or around the parentheses, respectively.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Bar(
+ x=["2020-01-01", "2020-04-01", "2020-07-01"],
+ y=[1000, 1500, 1700],
+ xperiod="M3",
+ xperiodalignment="middle",
+ xhoverformat="Q%q",
+ hovertemplate="%{y}%{_xother}"
+))
+
+fig.add_trace(go.Scatter(
+ x=["2020-01-01", "2020-02-01", "2020-03-01",
+ "2020-04-01", "2020-05-01", "2020-06-01",
+ "2020-07-01", "2020-08-01", "2020-09-01"],
+ y=[1100,1050,1200,1300,1400,1700,1500,1400,1600],
+ xperiod="M1",
+ xperiodalignment="middle",
+ hovertemplate="%{y}%{_xother}"
+))
+
+fig.update_layout(hovermode="x unified")
+fig.show()
+```
+
+
### Time Series Plot with Custom Date Range
The data range can be set manually using either `datetime.datetime` objects, or date strings.
+
```python
# Using plotly.express
diff --git a/doc/python/treemaps.md b/doc/python/treemaps.md
index 8aa3a9f217e..2bd9f3c74b0 100644
--- a/doc/python/treemaps.md
+++ b/doc/python/treemaps.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.3.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.3
+ version: 3.7.7
plotly:
description: How to make Treemap Charts with Plotly
display_as: basic
@@ -33,7 +33,7 @@ jupyter:
thumbnail: thumbnail/treemap.png
---
-[Treemap charts](https://en.wikipedia.org/wiki/Treemapping) visualize hierarchical data using nested rectangles. Same as [Sunburst](https://plotly.com/python/sunburst-charts/) the hierarchy is defined by [labels](https://plotly.com/python/reference/treemap/#treemap-labels) (`names` for `px.treemap`) and [parents](https://plotly.com/python/reference/treemap/#treemap-parents) attributes. Click on one sector to zoom in/out, which also displays a pathbar in the upper-left corner of your treemap. To zoom out you can use the path bar as well.
+[Treemap charts](https://en.wikipedia.org/wiki/Treemapping) visualize hierarchical data using nested rectangles. The input data format is the same as for [Sunburst Charts](https://plotly.com/python/sunburst-charts/) and [Icicle Charts](https://plotly.com/python/icicle-charts/): the hierarchy is defined by [labels](https://plotly.com/python/reference/treemap/#treemap-labels) (`names` for `px.treemap`) and [parents](https://plotly.com/python/reference/treemap/#treemap-parents) attributes. Click on one sector to zoom in/out, which also displays a pathbar in the upper-left corner of your treemap. To zoom out you can use the path bar as well.
### Basic Treemap with plotly.express
@@ -47,6 +47,8 @@ fig = px.treemap(
names = ["Eve","Cain", "Seth", "Enos", "Noam", "Abel", "Awan", "Enoch", "Azura"],
parents = ["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve"]
)
+fig.update_traces(root_color="lightgrey")
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -57,7 +59,9 @@ Hierarchical data are often stored as a rectangular dataframe, with different co
```python
import plotly.express as px
df = px.data.tips()
-fig = px.treemap(df, path=['day', 'time', 'sex'], values='total_bill')
+fig = px.treemap(df, path=[px.Constant("all"), 'day', 'time', 'sex'], values='total_bill')
+fig.update_traces(root_color="lightgrey")
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -71,11 +75,11 @@ If a `color` argument is passed, the color of a node is computed as the average
import plotly.express as px
import numpy as np
df = px.data.gapminder().query("year == 2007")
-df["world"] = "world" # in order to have a single root node
-fig = px.treemap(df, path=['world', 'continent', 'country'], values='pop',
+fig = px.treemap(df, path=[px.Constant("world"), 'continent', 'country'], values='pop',
color='lifeExp', hover_data=['iso_alpha'],
color_continuous_scale='RdBu',
color_continuous_midpoint=np.average(df['lifeExp'], weights=df['pop']))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -86,8 +90,9 @@ When the argument of `color` corresponds to non-numerical data, discrete colors
```python
import plotly.express as px
df = px.data.tips()
-df["all"] = "all" # in order to have a single root node
-fig = px.treemap(df, path=['all', 'sex', 'day', 'time'], values='total_bill', color='day')
+fig = px.treemap(df, path=[px.Constant("all"), 'sex', 'day', 'time'],
+ values='total_bill', color='day')
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -96,8 +101,9 @@ In the example below the color of Saturday and Sunday sectors is the same as Din
```python
import plotly.express as px
df = px.data.tips()
-df["all"] = "all" # in order to have a single root node
-fig = px.treemap(df, path=['all', 'sex', 'day', 'time'], values='total_bill', color='time')
+fig = px.treemap(df, path=[px.Constant("all"), 'sex', 'day', 'time'],
+ values='total_bill', color='time')
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -108,8 +114,10 @@ For more information about discrete colors, see the [dedicated page](/python/dis
```python
import plotly.express as px
df = px.data.tips()
-fig = px.treemap(df, path=['sex', 'day', 'time'], values='total_bill', color='time',
- color_discrete_map={'(?)':'black', 'Lunch':'gold', 'Dinner':'darkblue'})
+fig = px.treemap(df, path=[px.Constant("all"), 'sex', 'day', 'time'],
+ values='total_bill', color='time',
+ color_discrete_map={'(?)':'lightgrey', 'Lunch':'gold', 'Dinner':'darkblue'})
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -132,6 +140,8 @@ df = pd.DataFrame(
df["all"] = "all" # in order to have a single root node
print(df)
fig = px.treemap(df, path=['all', 'regions', 'sectors', 'vendors'], values='sales')
+fig.update_traces(root_color="lightgrey")
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -144,9 +154,11 @@ import plotly.graph_objects as go
fig = go.Figure(go.Treemap(
labels = ["Eve","Cain", "Seth", "Enos", "Noam", "Abel", "Awan", "Enoch", "Azura"],
- parents = ["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve"]
+ parents = ["", "Eve", "Eve", "Seth", "Seth", "Eve", "Eve", "Awan", "Eve"],
+ root_color="lightgrey"
))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -179,8 +191,8 @@ fig.add_trace(go.Treemap(
parents = parents,
values = [10, 14, 12, 10, 2, 6, 6, 1, 4],
textinfo = "label+value+percent parent+percent entry+percent root",
- ),
- row = 1, col = 1)
+ root_color="lightgrey"
+),row = 1, col = 1)
fig.add_trace(go.Treemap(
branchvalues = "total",
@@ -188,11 +200,10 @@ fig.add_trace(go.Treemap(
parents = parents,
values = [65, 14, 12, 10, 2, 6, 6, 1, 4],
textinfo = "label+value+percent parent+percent entry",
- outsidetextfont = {"size": 20, "color": "darkblue"},
- marker = {"line": {"width": 2}},
- pathbar = {"visible": False}),
- row = 1, col = 2)
+ root_color="lightgrey"
+),row = 1, col = 2)
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -205,14 +216,19 @@ There are three different ways to change the color of the sectors in Treemap:
```python
import plotly.graph_objects as go
-labels = ["A1", "A2", "A3", "A4", "A5", "B1", "B2"]
-parents = ["", "A1", "A2", "A3", "A4", "", "B1"]
+values = [0, 11, 12, 13, 14, 15, 20, 30]
+labels = ["container", "A1", "A2", "A3", "A4", "A5", "B1", "B2"]
+parents = ["", "container", "A1", "A2", "A3", "A4", "container", "B1"]
fig = go.Figure(go.Treemap(
labels = labels,
+ values = values,
parents = parents,
- marker_colors = ["pink", "royalblue", "lightgray", "purple", "cyan", "lightgray", "lightblue"]))
+ marker_colors = ["pink", "royalblue", "lightgray", "purple",
+ "cyan", "lightgray", "lightblue", "lightgreen"]
+))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -221,31 +237,39 @@ This example uses `treemapcolorway` attribute, which should be set in layout.
```python
import plotly.graph_objects as go
-labels = ["A1", "A2", "A3", "A4", "A5", "B1", "B2"]
-parents = ["", "A1", "A2", "A3", "A4", "", "B1"]
+values = [0, 11, 12, 13, 14, 15, 20, 30]
+labels = ["container", "A1", "A2", "A3", "A4", "A5", "B1", "B2"]
+parents = ["", "container", "A1", "A2", "A3", "A4", "container", "B1"]
fig = go.Figure(go.Treemap(
labels = labels,
- parents = parents
+ values = values,
+ parents = parents,
+ root_color="lightblue"
))
-fig.update_layout(treemapcolorway = ["pink", "lightgray"])
-
+fig.update_layout(
+ treemapcolorway = ["pink", "lightgray"],
+ margin = dict(t=50, l=25, r=25, b=25)
+)
fig.show()
```
```python
import plotly.graph_objects as go
-values = ["11", "12", "13", "14", "15", "20", "30"]
-labels = ["A1", "A2", "A3", "A4", "A5", "B1", "B2"]
-parents = ["", "A1", "A2", "A3", "A4", "", "B1"]
+values = [0, 11, 12, 13, 14, 15, 20, 30]
+labels = ["container", "A1", "A2", "A3", "A4", "A5", "B1", "B2"]
+parents = ["", "container", "A1", "A2", "A3", "A4", "container", "B1"]
fig = go.Figure(go.Treemap(
labels = labels,
values = values,
parents = parents,
- marker_colorscale = 'Blues'))
+ marker_colorscale = 'Blues'
+))
+
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -326,7 +350,7 @@ fig.add_trace(go.Treemap(
maxdepth=2
), 1, 2)
-fig.update_layout(margin=dict(t=10, b=10, r=10, l=10))
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -336,37 +360,22 @@ The following example uses hierarchical data that includes layers and grouping.
```python
import plotly.graph_objects as go
-from plotly.subplots import make_subplots
import pandas as pd
-df1 = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
-df2 = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/coffee-flavors.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
-fig = make_subplots(
- rows = 1, cols = 2,
- column_widths = [0.4, 0.4],
- specs = [[{'type': 'treemap', 'rowspan': 1}, {'type': 'treemap'}]]
-)
+fig = go.Figure()
-fig.add_trace(
- go.Treemap(
- ids = df1.ids,
- labels = df1.labels,
- parents = df1.parents),
- col = 1, row = 1)
-
-fig.add_trace(
- go.Treemap(
- ids = df2.ids,
- labels = df2.labels,
- parents = df2.parents,
- maxdepth = 3),
- col = 2, row = 1)
+fig.add_trace(go.Treemap(
+ ids = df.ids,
+ labels = df.labels,
+ parents = df.parents,
+ maxdepth=3,
+ root_color="lightgrey"
+))
-fig.update_layout(
- margin = {'t':0, 'l':0, 'r':0, 'b':0}
-)
+fig.update_layout(margin = dict(t=50, l=25, r=25, b=25))
fig.show()
```
@@ -375,17 +384,25 @@ fig.show()
If you want all the text labels to have the same size, you can use the `uniformtext` layout parameter. The `minsize` attribute sets the font size, and the `mode` attribute sets what happens for labels which cannot fit with the desired fontsize: either `hide` them or `show` them with overflow.
+*Note: animated transitions are currently not implemented when `uniformtext` is used.*
+
```python
import plotly.graph_objects as go
import pandas as pd
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/718417069ead87650b90472464c7565dc8c2cb1c/sunburst-coffee-flavors-complete.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/96c0bd/sunburst-coffee-flavors-complete.csv')
fig = go.Figure(go.Treemap(
- ids = df.ids,
- labels = df.labels,
- parents = df.parents))
-fig.update_layout(uniformtext=dict(minsize=10, mode='hide'))
+ ids = df.ids,
+ labels = df.labels,
+ parents = df.parents,
+ pathbar_textfont_size=15,
+ root_color="lightgrey"
+))
+fig.update_layout(
+ uniformtext=dict(minsize=10, mode='hide'),
+ margin = dict(t=50, l=25, r=25, b=25)
+)
fig.show()
```
diff --git a/doc/python/troubleshooting.md b/doc/python/troubleshooting.md
index 6f269abe52b..1742e1d9087 100644
--- a/doc/python/troubleshooting.md
+++ b/doc/python/troubleshooting.md
@@ -6,7 +6,7 @@ jupyter:
extension: .md
format_name: markdown
format_version: '1.2'
- jupytext_version: 1.6.0
+ jupytext_version: 1.4.2
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.6
+ version: 3.7.7
plotly:
description: How to troubleshoot import and rendering problems in Plotly with
Python.
@@ -37,7 +37,7 @@ jupyter:
### Version Problems
-In order to follow the examples in this documentation site, you should have the latest version of `plotly` installed (4.x), as detailed in the [Getting Started](/python/getting-started) guide. This documentation (under https://plotly.com/python) is incompatible with `plotly` version 3.x, for which the documentation is available under https://plotly.com/python/v3. In general you must also have the correct version of the underlying Plotly.js rendering engine installed, and the way to do that depends on the environment in which you are rendering figures: Dash, Jupyter Lab or Classic Notebook, VSCode etc. Read on for details about troubleshooting `plotly` in these environments.
+In order to follow the examples in this documentation site, you should have the latest version of `plotly` installed (5.x), as detailed in the [Getting Started](/python/getting-started) guide. This documentation (under https://plotly.com/python) is compatible with `plotly` version 4.x but *not* with version 3.x, for which the documentation is available under https://plotly.com/python/v3. In general you must also have the correct version of the underlying Plotly.js rendering engine installed, and the way to do that depends on the environment in which you are rendering figures: Dash, Jupyter Lab or Classic Notebook, VSCode etc. Read on for details about troubleshooting `plotly` in these environments.
### Import Problems
@@ -48,6 +48,8 @@ $ conda uninstall plotly
$ pip remove plotly
```
+> Problems can also arise if you have a file named `plotly.py` in the same directory as the code you are executing.
+
### Dash Problems
If you are encountering problems using `plotly` with [Dash](https://dash.plotly.com/) please first ensure that you have upgraded `dash` to the latest version, which will automatically upgrade `dash-core-components` to the latest version, ensuring that Dash is using an up-to-date version of the Plotly.js rendering engine for `plotly`. If this does not resolve your issue, please visit our [Dash Community Forum](https://community.plotly.com/) and we will be glad to help you out.
@@ -62,36 +64,47 @@ IFrame(snippet_url + 'renderers', width='100%', height=630)
```
-
### JupyterLab Problems
-In order to use `plotly` in JupyterLab, you *must have the extensions installed* as detailed in the [Getting Started guide](/python/getting-started). There is one extension: `plotlywidget`. Please note that the *extension version matters*: the extension versions in the [Getting Started](/python/getting-started) guide match the version of `plotly` at the top of the guide and so they should be installed together. Note also that these extensions are meant to work with JupyterLab 1 or above but not 0.x.
+In order to use `plotly` in JupyterLab, you *must have the `jupyterlab-plotly` extension installed* as detailed in the [Getting Started guide](/python/getting-started). When you install `plotly`, this extension is automatically made available to any JupyterLab 3.x installation in the same Python environment.
-To list your current extensions, run the following command in a terminal shell **from the same environment as JupyterLab was launched**:
+To list your current extensions, run the following command in a terminal shell **from the same environment as JupyterLab is launched**:
```bash
+# Check that jupyterlab-plotly is installed
$ jupyter labextension list
```
-If you have [installed additional python environments](https://ipython.readthedocs.io/en/stable/install/kernel_install.html) (or kernels) to use with JupyterLab, or if you are using a centrally hosted JupyterLab installation, you need to make sure that the extensions are installed in the python environment used to launch JupyterLab (the "server" environment). If you accidentally installed the extensions (and run the command above) in one of the additional python environments ("processing" environments), then it is possible for the command above to list the correct extensions but for them to not be available in the JupyterLab front-end you have loaded in your browser. To check if this is the problem, you can [look at the active extension list through your browser via the JupyterLab Extension Manager](https://jupyterlab.readthedocs.io/en/stable/user/extensions.html#using-the-extension-manager), which will always list the extensions in the "server" environment. To summarize: if you use JupyterLab with multiple python environments, the extensions must be installed in the "server" environment, and the plotly python library must be installed in each "processing" environment that you intend to use.
+Please note that the *extension version matters*: the extension versions in the [Getting Started](/python/getting-started) guide match the version of `plotly` at the top of the guide and so they should be installed together. Note also that these extensions are meant to work with JupyterLab 1 or above but not 0.x.
-> Version 4.14.3 or earlier needed two extensions (`jupyterlab-plotly` and `plotlywidget`) to be installed manually running:
+If automatic installation of the extension is not working in your environment, or if you are using JupyterLab 1.x or 2.0, you may install it manually using the following command, which requires `node` to be installed.
```bash
-$ jupyter labextension install jupyterlab-plotly @jupyter-widgets/jupyterlab-manager plotlywidget
+# Manually reinstall the extension
+$ jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyterlab-plotly
```
-#### JupyterLab 2 and earlier
+If you have [installed additional python environments](https://ipython.readthedocs.io/en/stable/install/kernel_install.html) (or kernels) to use with JupyterLab, or if you are using a centrally hosted JupyterLab installation, you need to make sure that the extensions are installed in the python environment used to launch JupyterLab (the "server" environment). If you accidentally installed the extensions (and run the command above) in one of the additional python environments ("processing" environments), then it is possible for the command above to list the correct extensions but for them to not be available in the JupyterLab front-end you have loaded in your browser. To check if this is the problem, you can [look at the active extension list through your browser via the JupyterLab Extension Manager](https://jupyterlab.readthedocs.io/en/stable/user/extensions.html#using-the-extension-manager), which will always list the extensions in the "server" environment. To summarize: if you use JupyterLab with multiple python environments, the extensions must be installed in the "server" environment, and the plotly python library must be installed in each "processing" environment that you intend to use.
+
+> Note that version 4.14.3 of `plotly` or earlier needed two extensions (`jupyterlab-plotly` and `plotlywidget`) to be installed manually running, and that `plotlywidget` requires `@jupyter-widgets/jupyterlab-manager` to be installed:
+
+```bash
+# Instructions for `plotly` 4.x
+$ jupyter labextension install jupyterlab-plotly plotlywidget @jupyter-widgets/jupyterlab-manager
+```
-If you have the correct version of the extensions installed and active in your active JupyterLab sessions and are still seeing problems, the issue may clear up if you rebuild JupyterLab. This shouldn't be required in principle but many users have resolved their issues this way. To rebuild JupyterLab, shut down JupyterLab and run the following command in a terminal shell **from the same environment as JupyterLab was launched**:
+If you have the correct version(s) of the extension(s) installed and active in your active JupyterLab sessions and are still seeing problems, the issue may clear up if you rebuild JupyterLab. This shouldn't be required in principle but some users have resolved their issues this way. To rebuild JupyterLab, shut down JupyterLab and run the following command in a terminal shell **from the same environment as JupyterLab was launched**:
```bash
+# rebuilding JupyterLab
$ jupyter lab build
```
To uninstall your Plotly extensions prior to reinstalling them, run the following commands in a terminal shell before reinstalling them by following the instructions in the [Getting Started guide](/python/getting-started):
```bash
+# uninstalling extensions to reinstall
+$ jupyter labextension uninstall jupyterlab-plotly
$ jupyter labextension uninstall plotlywidget
```
diff --git a/doc/python/webgl-vs-svg.md b/doc/python/webgl-vs-svg.md
index af2bc7cbef2..212932c1335 100644
--- a/doc/python/webgl-vs-svg.md
+++ b/doc/python/webgl-vs-svg.md
@@ -22,7 +22,7 @@ jupyter:
pygments_lexer: ipython3
version: 3.6.5
plotly:
- description: Implement WebGL for increased speed, improved interactivity, and
+ description: Using WebGL for increased speed, improved interactivity, and
the ability to plot even more data!
display_as: basic
language: python
@@ -31,20 +31,46 @@ jupyter:
order: 14
permalink: python/webgl-vs-svg/
thumbnail: thumbnail/webgl.jpg
+ redirect_from: python/compare-webgl-svg/
---
-Here we show that it is possible to represent millions of points with WebGL.
+### SVG and canvas/WebGL: two browser capabilities for rendering
+
+`plotly` figures are rendered by web browsers, which broadly speaking have two families of capabilities for rendering graphics: the SVG API which supports vector rendering, and the Canvas API which supports raster rendering, and can exploit GPU hardware acceleration via a browser technology known as WebGL. Each `plotly` trace type is primarily rendered with either SVG or WebGL, although WebGL-powered traces also use some SVG. The following trace types use WebGL for part or all of the rendering:
+
+* Accelerated versions of SVG trace types: `scattergl`, `scatterpolargl`, `heatmapgl`
+* High-performance multidimensional trace types: `splom`, or `parcoords`
+* 3-d trace types `scatter3d`, `surface`, `mesh3d`, `cone`, `streamtube`
+* Mapbox Gl JS-powered trace types: `scattermapbox`, `choroplethmapbox`, `densitymapbox`
+
+### WebGL Limitations and Tradeoffs
+
+WebGL is a powerful technology for accelerating computation but comes with some strict limitations:
+
+1. GPU requirement: WebGL is a GPU (graphics card) technology and therefore requires specific hardware which is available in most but not all cases and is supported by most but not all browsers
+2. Rasterization: WebGL-rendered data is drawn as a grid of pixels rather than as individual shapes, so can appear pixelated or fuzz in certain cases, and when exported to static file formats will appear pixelated on zoom. In addition: text rendering will differ between SVG and WebGL-powered traces.
+3. Context limits: browsers impose a strict limit on the number of WebGL "contexts" that any given web document can access. WebGL-powered traces in `plotly` can use multiple contexts in some cases but as a general rule, **it may not be possible to render more than 8 WebGL-involving figures on the same page at the same time.**
+4. Size limits: browsers impose hardware-dependent limits on the height and width of figures using WebGL which users may encounter with extremely large plots (e.g. tens of thousands of pixels of height)
+
+In addition to the above limitations, the WebGL-powere version of certain SVG-powered trace types (`scattergl`, `scatterpolargl`, `heatmapgl`) are not complete drop-in replacements for their SVG counterparts yet
+* Available symbols will differ
+* Area fills are not yet supported in WebGL
+* Range breaks on time-series axes are not yet supported
+* Axis range heuristics may differ
+
+### WebGL for Scatter Performance
+
+In the examples below we show that it is possible to represent up to around a million points with WebGL-enabled traces.
For larger datasets, or for a clearer visualization of the density of points,
it is also possible to use [datashader](/python/datashader/).
-#### Compare WebGL and SVG
-Checkout [this notebook](https://plotly.com/python/compare-webgl-svg) to compare WebGL and SVG scatter plots with 75,000 random data points
+### WebGL with Plotly Express
-#### WebGL with Plotly Express
+The `rendermode` argument to supported Plotly Express functions (e.g. `scatter` and `scatter_polar`) can be used to enable WebGL rendering.
-The `rendermode` argument to supported Plotly Express functions can be used to enable WebGL rendering.
+> **Note** The default `rendermode` is `"auto"`, in which case Plotly Express will automatically set `rendermode="webgl` if the input data is more than 1,000 rows long. If WebGL acceleration is *not* desired in this case, `rendermode` can be forced to `"svg"` for vectorized, if slower, rendering.
-Here is an example that creates a 100,000 point scatter plot using Plotly Express with WebGL rendering enabled.
+Here is an example that creates a 100,000 point scatter plot using Plotly Express with WebGL rendering explicitly enabled.
```python
import plotly.express as px
@@ -65,9 +91,10 @@ fig.update_traces(marker_line=dict(width=1, color='DarkSlateGray'))
fig.show()
```
-#### WebGL with 100,000 points
-The `Scattergl` trace type can be used to create a WebGL enabled scatter plot.
+#### WebGL with 100,000 points with Graph Objects
+
+If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Scattergl` class from `plotly.graph_objects`](/python/graph-objects/).
```python
import plotly.graph_objects as go
@@ -95,7 +122,7 @@ fig.add_trace(
fig.show()
```
-#### WebGL with 1 Million Points
+#### WebGL Rendering with 1 Million Points
```python
import plotly.graph_objects as go
@@ -149,4 +176,4 @@ fig.show()
### Reference
-See https://plotly.com/python/reference/scattergl/ for more information and chart attribute options!
\ No newline at end of file
+See https://plotly.com/python/reference/scattergl/ for more information and chart attribute options!
diff --git a/packages/javascript/jupyterlab-plotly/package-lock.json b/packages/javascript/jupyterlab-plotly/package-lock.json
index 4b8ca16abc9..71bbf887b16 100644
--- a/packages/javascript/jupyterlab-plotly/package-lock.json
+++ b/packages/javascript/jupyterlab-plotly/package-lock.json
@@ -1,6 +1,6 @@
{
"name": "jupyterlab-plotly",
- "version": "5.0.0-rc.2",
+ "version": "5.0.0",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
diff --git a/packages/javascript/jupyterlab-plotly/package.json b/packages/javascript/jupyterlab-plotly/package.json
index 101ff97b483..a58e6b0a727 100644
--- a/packages/javascript/jupyterlab-plotly/package.json
+++ b/packages/javascript/jupyterlab-plotly/package.json
@@ -1,6 +1,6 @@
{
"name": "jupyterlab-plotly",
- "version": "5.0.0-rc.2",
+ "version": "5.0.0",
"description": "The plotly Jupyter extension",
"author": "The plotly.py team",
"license": "MIT",
diff --git a/packages/python/plotly/plotly/_widget_version.py b/packages/python/plotly/plotly/_widget_version.py
index e7577906fbb..adf6c410c34 100644
--- a/packages/python/plotly/plotly/_widget_version.py
+++ b/packages/python/plotly/plotly/_widget_version.py
@@ -2,4 +2,4 @@
# for automated dev builds
#
# It is edited by hand prior to official releases
-__frontend_version__ = "^5.0.0-rc.2"
+__frontend_version__ = "^5.0.0"
diff --git a/packages/python/plotly/recipe/conda_build_config.yaml b/packages/python/plotly/recipe/conda_build_config.yaml
new file mode 100644
index 00000000000..abcf8353472
--- /dev/null
+++ b/packages/python/plotly/recipe/conda_build_config.yaml
@@ -0,0 +1,2 @@
+python:
+ - 3.6
diff --git a/release.md b/release.md
index 54e47b3bab9..160aa6c5113 100644
--- a/release.md
+++ b/release.md
@@ -11,7 +11,7 @@ releases and forum announcements to do :)
This is the release process for releasing `plotly.py` version `X.Y.Z` with
`jupyterlab-plotly` with matching versions.
-> Note: it's easier to lock all three versions together, even if it means we occasionally
+> Note: it's easier to lock the JS extension and Python versions together, even if it means we occasionally
> push no-change versions to NPM/PyPI/Conda.
### Finalize changelog