Skip to content

Commit f6654a2

Browse files
LiamConnorsLiamConnors
committed
Add back v4 migration
1 parent d6716cd commit f6654a2

File tree

1 file changed

+294
-0
lines changed

1 file changed

+294
-0
lines changed

‎doc/python/v4-migration.md

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
---
2+
jupyter:
3+
jupytext:
4+
notebook_metadata_filter: all
5+
text_representation:
6+
extension: .md
7+
format_name: markdown
8+
format_version: '1.1'
9+
jupytext_version: 1.1.1
10+
kernelspec:
11+
display_name: Python 3
12+
language: python
13+
name: python3
14+
language_info:
15+
codemirror_mode:
16+
name: ipython
17+
version: 3
18+
file_extension: .py
19+
mimetype: text/x-python
20+
name: python
21+
nbconvert_exporter: python
22+
pygments_lexer: ipython3
23+
version: 3.6.7
24+
plotly:
25+
description: Migration guide for upgrading from version 3 to version 4
26+
display_as: file_settings
27+
language: python
28+
layout: base
29+
name: Version 4 Migration Guide
30+
order: 8
31+
page_type: example_index
32+
permalink: python/v4-migration/
33+
thumbnail: thumbnail/v4-migration.png
34+
---
35+
36+
### Upgrading to Version 4
37+
38+
Upgrading to version 4 of `plotly` is a matter of following the instructions in the [Getting Started](/python/getting-started/) guide and reinstalling the packages, subject to the notices below.
39+
40+
### Getting Help
41+
42+
If you encounter issues in upgrading from version 3 to version 4, please reach out in our [Community Forum](https://community.plotly.com/c/api/python) or if you've found an issue or regression in version 4, please report a [Github Issue](https://github.com/plotly/plotly.py/issues/new)
43+
44+
<!-- #region -->
45+
### Online features (`plotly.plotly`) moved to `chart-studio` package
46+
47+
Prior versions of plotly.py contained functionality for creating figures in both "online" and "offline" modes. In "online" mode figures were uploaded to the Chart Studio cloud (or on-premise) service, whereas in "offline" mode figures were rendered locally. **Version 4 of `plotly` is "offline"-only: all "online" functionality has been removed from the main `plotly` distribution package and moved to the new `chart-studio` distribution package.**
48+
49+
To migrate version 3 "online" functionality, first install the `chart-studio` package using pip...
50+
51+
```
52+
$ pip install chart-studio
53+
```
54+
55+
or conda.
56+
57+
```
58+
$ conda install -c plotly chart-studio
59+
```
60+
61+
Then, update your Python import statements to import "online" functionality from the top-level `chart_studio` package, rather than the top-level `plotly` package. For example. replace
62+
63+
```python
64+
from plotly.plotly import plot, iplot
65+
```
66+
67+
with
68+
69+
```python
70+
from chart_studio.plotly import plot, iplot
71+
```
72+
73+
Similarly,
74+
- Replace **`plotly.api`** with **`chart_studio.api`**
75+
- Replace **`plotly.dashboard_objs`** with **`chart_studio.dashboard_objs`**
76+
- Replace **`plotly.grid_objs`** with **`chart_studio.grid_objs`**
77+
- Replace **`plotly.presentation_objs`** with **`chart_studio.presentation_objs`**
78+
- Replace **`plotly.widgets`** with **`chart_studio.widgets`**
79+
<!-- #endregion -->
80+
81+
<!-- #region -->
82+
### Offline features (`plotly.offline`) replaced by Renderers framework & HTML export
83+
84+
Version 4 introduces a new renderers framework that is a generalization of version 3's `plotly.offline.init_notebook_mode` and `plotly.offline.iplot` functions for displaying figures. *This is a non-breaking change*: the `plotly.offline.iplot` function is still available and has been reimplemented on top of the renderers framework, so no changes are required when porting to version 4. Going forward, we recommend using the renderers framework directly. See [Displaying plotly figures](/python/renderers) for more information.
85+
86+
87+
In version 3, the `plotly.offline.plot` function was used to export figures to HTML files. In version 4, this function has been reimplemented on top of the new `to_html` and `write_html` functions from the `plotly.io` module. These functions have a slightly more consistent API (see docstrings for details), and going forward we recommend using them directly when performing HTML export. When working with a graph object figure, these functions are also available as the `.to_html` and `.write_html` figure methods.
88+
<!-- #endregion -->
89+
90+
### New default theme
91+
An updated `"plotly"` theme has been enabled by default in version 4.
92+
93+
```python
94+
import plotly.graph_objects as go
95+
from plotly.subplots import make_subplots
96+
import pandas as pd
97+
98+
# Make figure with subplots
99+
fig = make_subplots(rows=1, cols=2, specs=[[{"type": "bar"},
100+
{"type": "surface"}]])
101+
102+
# Add bar traces to subplot (1, 1)
103+
fig.add_trace(go.Bar(y=[2, 1, 3]), row=1, col=1)
104+
fig.add_trace(go.Bar(y=[3, 2, 1]), row=1, col=1)
105+
fig.add_trace(go.Bar(y=[2.5, 2.5, 3.5]), row=1, col=1)
106+
107+
# Add surface trace to subplot (1, 2)
108+
# Read data from a csv
109+
z_data = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv")
110+
fig.add_surface(z=z_data)
111+
112+
# Hide legend
113+
fig.update_layout(
114+
showlegend=False,
115+
title_text="Default Theme",
116+
height=500,
117+
width=800,
118+
)
119+
120+
fig.show()
121+
```
122+
123+
You can revert to the version 3 figure appearance by disabling the default theme as follows:
124+
125+
```python
126+
import plotly.io as pio
127+
pio.templates.default = "none"
128+
129+
import plotly.graph_objects as go
130+
from plotly.subplots import make_subplots
131+
import pandas as pd
132+
133+
# Make figure with subplots
134+
fig = make_subplots(rows=1, cols=2, specs=[[{"type": "bar"},
135+
{"type": "surface"}]])
136+
137+
# Add bar traces to subplot (1, 1)
138+
fig.add_trace(go.Bar(y=[2, 1, 3]), row=1, col=1)
139+
fig.add_trace(go.Bar(y=[3, 2, 1]), row=1, col=1)
140+
fig.add_trace(go.Bar(y=[2.5, 2.5, 3.5]), row=1, col=1)
141+
142+
# Add surface trace to subplot (1, 2)
143+
# Read data from a csv
144+
z_data = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv")
145+
fig.add_surface(z=z_data)
146+
147+
# Hide legend
148+
fig.update_layout(
149+
showlegend=False,
150+
title_text="Default Theme Disabled",
151+
height=500,
152+
width=800,
153+
)
154+
155+
fig.show()
156+
```
157+
158+
```python
159+
# Restore default theme
160+
pio.templates.default = "plotly"
161+
```
162+
163+
See [Theming and templates](/python/templates) for more information on theming in plotly.py version 4.
164+
165+
### Add trace return value
166+
In version 3, the `add_trace` graph object figure method returned a reference to the newly created trace. This was also the case for the `add_{trace_type}` methods (e.g. `add_scatter`, `add_bar`, etc.). In version 4, these methods return a reference to the calling figure. This change was made to support method chaining of figure operations. For example
167+
168+
```python
169+
from plotly.subplots import make_subplots
170+
(make_subplots(rows=1, cols=2)
171+
.add_scatter(y=[2, 1, 3], row=1, col=1)
172+
.add_bar(y=[3, 2, 1], row=1, col=2)
173+
.update_layout(
174+
title_text="Figure title",
175+
showlegend=False,
176+
width=800,
177+
height=500,
178+
)
179+
.show())
180+
```
181+
182+
<!-- #region -->
183+
Code that relied on the `add_*` methods to return a reference to the newly created trace will need to be updated to access the trace from the returned figure. This can be done by appending `.data[-1]` to the add trace expression.
184+
185+
Here is an example of a version 3 code snippet that adds a scatter trace to a figure, assigns the result to a variable named `scatter`, and then modifies the marker size of the scatter trace.
186+
187+
```python
188+
import plotly.graph_objs as go
189+
fig = go.Figure()
190+
scatter = fig.add_trace(go.Scatter(y=[2, 3, 1]))
191+
scatter.marker.size = 20
192+
```
193+
In version 4, this would be replaced with the following:
194+
195+
```python
196+
import plotly.graph_objects as go
197+
fig = go.Figure()
198+
scatter = fig.add_trace(go.Scatter(y=[2, 3, 1])).data[-1]
199+
scatter.marker.size = 20
200+
```
201+
<!-- #endregion -->
202+
203+
### `make_subplots` updates
204+
The `make_subplots` function has been overhauled to support all trace types and to support the integration of Plotly Express. Here are a few changes to be aware of when porting code that uses `make_subplots` to version 4.
205+
206+
#### New preferred import location
207+
The preferred import location of the `make_subplots` function is now `plotly.subplots.make_subplots`. For compatibility, this function is still available as `plotly.tools.make_subplots`.
208+
209+
#### Grid no longer printed by default
210+
When the `print_grid` argument to `make_subplots` is set to `True`, a text representation of the subplot grid is printed by the `make_subplots` function. In version 3, the default value of `print_grid` was `True`. In version 4, the default value of `print_grid` is `False`.
211+
212+
#### New `row_heights` argument to replace `row_width`
213+
The legacy argument for specifying the relative height of subplot rows was called `row_width`. A new `row_heights` argument has been introduced for this purpose.
214+
215+
> Note: Although it is not mentioned in the docstring for `plotly.subplots.make_subplots`, the legacy `row_width` argument, with the legacy behavior, is still available in version 4.
216+
217+
In addition to having a more consistent name, values specified to the new `row_heights` argument properly honor the `start_cell` argument. With the legacy `row_width` argument, the list of heights was always interpreted from the bottom row to the top row, even if `start_cell=="top-left"`. With the new `row_heights` argument, the list of heights is interpreted from top to bottom if `start_cell=="top-left"` and from bottom to top if `start_cell=="bottom-left"`.
218+
219+
When porting code from `row_width` to `row_heights`, the order of the heights list must be reversed if `start_cell=="top-left"` or `start_cell` was unspecified.
220+
221+
Here is a version 3 compatible example that uses the `row_width` argument to create a figure with subplots where the top row is twice as tall as the bottom row.
222+
223+
```python
224+
from plotly.subplots import make_subplots
225+
226+
fig = make_subplots(
227+
rows=2, cols=1,
228+
row_width=[0.33, 0.67],
229+
start_cell="top-left")
230+
231+
fig.add_scatter(y=[2, 1, 3], row=1, col=1)
232+
fig.add_bar(y=[2, 3, 1], row=2, col=1)
233+
fig.show()
234+
```
235+
236+
And here is the equivalent, version 4 example. Note how the order to the height list is reversed compared to the example above.
237+
238+
```python
239+
from plotly.subplots import make_subplots
240+
241+
fig = make_subplots(
242+
rows=2, cols=1,
243+
row_heights=[0.67, 0.33],
244+
start_cell="top-left")
245+
246+
fig.add_scatter(y=[2, 1, 3], row=1, col=1)
247+
fig.add_bar(y=[2, 3, 1], row=2, col=1)
248+
fig.show()
249+
```
250+
251+
#### Implementation of shared axes with `make_subplots`
252+
The implementation of shared axis support in the `make_subplots` function has been simplified. Prior to version 4, shared y-axes were implemented by associating a single `yaxis` object with multiple `xaxis` objects, and vica versa.
253+
254+
In version 4, every 2D Cartesian subplot has a dedicated x-axis and and a dedicated y-axis. Axes are now "shared" by being linked together using the `matches` axis property.
255+
256+
For legacy code that makes use of the `make_subplots` and add trace APIs, this change does not require any action on the user's part. However, legacy code that uses `make_subplots` to create a figure with shared axes, and then manipulates the axes directly, may require updates. The output of the `.print_grid` method on a figure created using `make_subplots` can be used to identify which axis objects are associated with each subplot.
257+
258+
```python
259+
from plotly.subplots import make_subplots
260+
fig = make_subplots(rows=1, cols=2, shared_yaxes=True)
261+
fig.print_grid()
262+
print(fig)
263+
```
264+
265+
### Trace UIDs
266+
In version 3, all trace graph objects were copied and assigned a new `uid` property when being added to a `Figure`. In version 4, these `uid` properties are only generated automatically when a trace is added to a `FigureWidget`. When a trace is added to a standard `Figure` graph object the input `uid`, if provided, is accepted as is.
267+
268+
### Timezones
269+
Prior to version 4, when plotly.py was passed a `datetime` that included a timezone, the `datetime` was automatically converted to UTC. In version 4, this conversion is no longer performed, and `datetime` objects are accepted and displayed in local time.
270+
271+
<!-- #region -->
272+
### Headless image export on Linux with Xvfb.
273+
In version 4, the static image export logic attempts to automatically detect whether to call the orca image export utility using Xvfb. Xvfb is needed for orca to work in a Linux environment if an X11 display server is not available. By default, Xvfb is used if plotly.py is running on Linux if no X11 display server is detected and `Xvfb` is available on the system `PATH`.
274+
275+
This new behavior can be disabled by setting the `use_xvfb` orca configuration option to `False` as follows:
276+
277+
```python
278+
import plotly.io as pio
279+
pio.orca.config.use_xvfb = False
280+
```
281+
<!-- #endregion -->
282+
283+
### Removals
284+
285+
#### fileopt argument removal
286+
The `fileopt` argument to `chart_studio.plotly.plot` has been removed, so in-place modifications to previously published figures are no longer supported.
287+
288+
#### Legacy online `GraphWidget`
289+
The legacy online-only `GraphWidget` class has been removed. Please use the `plotly.graph_objects.FigureWidget` class instead. See the [Figure Widget Overview](/python/figurewidget/) for more information.
290+
291+
### Recommended style updates
292+
293+
#### Import from `graph_objects` instead of `graph_objs`
294+
The legacy `plotly.graph_objs` package has been aliased as `plotly.graph_objects` because the latter is much easier to communicate verbally. The `plotly.graph_objs` package is still available for backward compatibility.

0 commit comments

Comments
 (0)