You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+18-1
Original file line number
Diff line number
Diff line change
@@ -2,17 +2,34 @@
2
2
All notable changes to this project will be documented in this file.
3
3
This project adheres to [Semantic Versioning](http://semver.org/).
4
4
5
+
5
6
## [4.9.0] - unreleased
6
7
7
8
### Updated
8
9
9
10
- Added all cartesian-2d Plotly Express functions, plus `imshow` to Pandas backend with `kind` option
11
+
-`plotly.express.imshow` now uses data frame index and columns names and values to populate axis parameters by default ([#2539](https://github.com/plotly/plotly.py/pull/2539))
12
+
13
+
14
+
## [4.8.2] - 2020-06-26
15
+
16
+
### Updated
17
+
18
+
- Updated Plotly.js to version 1.54.5. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.5/CHANGELOG.md) for more information.
19
+
-`add_traces()` now accepts bare `int`-like values for `rows`/`cols` as well as lists thereof ([#2546](https://github.com/plotly/plotly.py/pull/2546)), with thanks to [@MCBoarder289](https://github.com/MCBoarder289) for the contribution!
10
20
11
-
## [4.8.2] - unreleased
12
21
13
22
### Fixed
14
23
24
+
-`row`/`col` now accept `int`-like values, not strictly `int` values ([#2451](https://github.com/plotly/plotly.py/pull/2451)), with thanks to [@MCBoarder289](https://github.com/MCBoarder289) for the contribution!
15
25
- Fixed special cases with `px.sunburst` and `px.treemap` with `path` input ([#2524](https://github.com/plotly/plotly.py/pull/2524))
26
+
- Fixed bug in `hover_data` argument of `px` functions, when the column name is changed with labels and `hover_data` is a dictionary setting up a specific format for the hover data ([#2544](https://github.com/plotly/plotly.py/pull/2544)).
27
+
- Made the Plotly Express `trendline` argument more robust and made it work with datetime `x` values ([#2554](https://github.com/plotly/plotly.py/pull/2554))
28
+
- Fixed bug in `px.sunburst` and `px.treemap`: when the `color` and `values` arguments correspond to the same column, a different aggregation function has to be used for the two arguments ([#2591](https://github.com/plotly/plotly.py/pull/2591))
29
+
- Plotly Express wide mode now accepts mixed integer and float columns ([#2598](https://github.com/plotly/plotly.py/pull/2598))
30
+
- Plotly Express `range_(x|y)` should not impact the unlinked range of marginal subplots ([#2600](https://github.com/plotly/plotly.py/pull/2600))
31
+
-`px.line` now sets `line_group=<variable>` in wide mode by default ([#2599](https://github.com/plotly/plotly.py/pull/2599))
32
+
- Corrected some regex warnings ([#2577](https://github.com/plotly/plotly.py/pull/2577)), with thanks to [@georgevdd](https://github.com/georgevdd) for the contribution!
If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Scatter3D` from `plotly.graph_objs`.
79
+
If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Scatter3D`class from `plotly.graph_objects`](/python/graph-objects/).
80
80
Like the [2D scatter plot](https://plotly.com/python/line-and-scatter/)`go.Scatter`, `go.Scatter3d` plots individual data in three-dimensional space.
* Animations are designed to work well when each row of input is present across all animation frames, and when categorical values mapped to symbol, color and facet are constant across frames. Animations *may be misleading or inconsistent* if these constraints are not met.
57
+
* Although Plotly Express supports animation for many chart and map types, smooth inter-frame transitions are today only possible for scatter and bar
58
+
* Plotly Express will not automatically compute the union of all x/y/color ranges, so these must be specified manually to avoid scale jumps across frames
59
+
54
60
#### Animated figures with Graph Objects
55
61
56
62
The remainder of this section describes the low-level API for constructing animated figures manually.
Copy file name to clipboardExpand all lines: doc/python/bar-charts.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -99,7 +99,7 @@ To learn more, see the _link to px.bar reference page_.
99
99
100
100
#### Basic Bar Chart with plotly.graph_objects
101
101
102
-
If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Bar`function from `plotly.graph_objects`.
102
+
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/).
Copy file name to clipboardExpand all lines: doc/python/box-plots.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -134,7 +134,7 @@ fig.show()
134
134
135
135
## Box plot with go.Box
136
136
137
-
If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Box`function from `plotly.graph_objects`. All available options for `go.Box` are described in the reference page https://plotly.com/python/reference/#box.
137
+
If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Box`class from `plotly.graph_objects`](/python/graph-objects/). All available options for `go.Box` are described in the reference page https://plotly.com/python/reference/#box.
Copy file name to clipboardExpand all lines: doc/python/bubble-charts.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -52,7 +52,7 @@ fig.show()
52
52
53
53
## Bubble Chart with plotly.graph_objects
54
54
55
-
If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Scatter` from `plotly.graph_objects`, and define the size of markers to create a bubble chart. All of the available options are described in the scatter section of the reference page: https://plotly.com/python/reference#scatter.
55
+
If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Scatter`class from `plotly.graph_objects`](/python/graph-objects/), and define the size of markers to create a bubble chart. All of the available options are described in the scatter section of the reference page: https://plotly.com/python/reference#scatter.
Copy file name to clipboardExpand all lines: doc/python/creating-and-updating-figures.md
+31-48
Original file line number
Diff line number
Diff line change
@@ -37,17 +37,13 @@ jupyter:
37
37
v4upgrade: true
38
38
---
39
39
40
-
### Representing Figures
40
+
The `plotly` Python package exists to create, manipulate and [render](/python/renderers/) graphical figures (i.e. charts, plots, maps and diagrams) represented by [data structures also referred to as figures](/python/figure-structure/). The rendering process uses the [Plotly.js JavaScript library](https://plotly.com/javascript/) under the hood although Python developers using this module very rarely need to interact with the Javascript library directly, if ever. Figures can be represented in Python either as dicts or as instances of the `plotly.graph_objects.Figure` class, and are serialized as text in [JavaScript Object Notation (JSON)](https://json.org/) before being passed to Plotly.js.
41
41
42
-
The goal of the plotly.py package is to provide a pleasant Python interface for creating figure specifications which are displayed by the [plotly.js](https://plot.ly/javascript) JavaScript graphing library.
42
+
> Note: the recommended entry-point into the plotly package is the [high-level plotly.express module, also known as Plotly Express](/python/plotly-express/), which consists of Python functions which return fully-populated `plotly.graph_objects.Figure` objects. This page exists to document the structure of the data structure that these objects represent for users who wish to understand more about how to customize them, or assemble them from other `plotly.graph_objects` components.
43
43
44
-
In the context of the plotly.js library, a figure is specified by a declarative [JSON](https://www.json.org/json-en.html) data structure.
44
+
### Figures As Dictionaries
45
45
46
-
Therefore, you should always keep in mind as you are creating and updating figures using the plotly.py package that its ultimate goal is to help users produce Python [dictionaries](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) that can be automatically [serialized](https://en.wikipedia.org/wiki/Serialization) into the JSON data structure that the plotly.js graphing library understands.
47
-
48
-
#### Figures As Dictionaries
49
-
50
-
The `fig` dictonary in the example below describes a figure. It contains a single `bar` trace and a title.
46
+
At a low level, figures can be represented as dictionaries and displayed using functions from the `plotly.io` module. The `fig` dictonary in the example below describes a figure. It contains a single `bar` trace and a title.
51
47
52
48
```python
53
49
fig =dict({
@@ -63,37 +59,21 @@ import plotly.io as pio
63
59
pio.show(fig)
64
60
```
65
61
66
-
Let's take a closer look at structure of the `fig` dictionary in order to better understand how `plotly.py` figures are built.
67
-
68
-
##### The `"data"` Key
69
-
70
-
The `"data"` key stores the value of list which describes the trace or traces which make up a figure. It is still a list even if the figure only contains one trace, as in the example above.
71
-
72
-
Each trace in the list stored by the `"data"` key is itself defined by a dictionary. The type of the trace (`"bar"`, `"scatter"`, `"contour"`, etc...) is specified with a `"type"` key, and the rest of the keys in a trace specification dictionary (`x`, `y`, etc...) are used to define the properties specific to the trace of that type.
73
-
74
-
##### The `"layout"` Key
62
+
### Figures as Graph Objects
75
63
76
-
The`"layout"` key stores a dictionary that specifies properties related to customizing how the figure looks, such as its title, typography, margins, axes, annotations, shapes, legend and more. In contrast to trace configuration options, which apply only to individual traces, layout configuration options apply to the figure as a whole.
64
+
The[`plotly.graph_objects` module provides an automatically-generated hierarchy of classes](https://plotly.com/python-api-reference/plotly.graph_objects.html) called ["graph objects"](/python/graph-objects/) that may be used to represent figures, with a top-level class `plotly.graph_objects.Figure`.
77
65
78
-
The [_Full Reference_](https://plot.ly/python/reference/) page contains descriptions of all of the supported trace and layout attributes and configuration options.
66
+
> Note that the *recommended alternative* to working with Python dictionaries is to [create entire figures at once using Plotly Express](/python/plotly-express/)and to manipulate the resulting `plotly.graph_objects.Figure` objects as described in this page, wherever possible, rather than to assemble figures bottom-up from underlying graph objects. See ["When to use Graph Objects"](/python/graph-objects/).
79
67
80
-
If working from the _Full Reference_ to build figures as Python dictionaries and lists suites your needs, go for it!
81
-
82
-
This is a perfectly valid way to use `plotly.py` to build figures. On the other hand, if you would like to use an API that offers you a bit more assistance in the figure creation process, read on to learn about `graph objects`.
83
-
84
-
#### Figures as Graph Objects
85
-
86
-
As an alternative to working with Python dictionaries, the `plotly.py` graphing library provides a hierarchy of classes called "graph objects" that may be used to construct figures. Graph objects have several benefits compared to plain Python dictionaries.
68
+
Graph objects have several benefits compared to plain Python dictionaries.
87
69
88
70
1. Graph objects provide precise data validation. If you provide an invalid property name or an invalid property value as the key to a graph object, an exception will be raised with a helpful error message describing the problem. This is not the case if you use plain Python dictionaries and lists to build your figures.
89
-
90
-
2. Graph objects contain descriptions of each valid property as Python `docstrings`. You can use these `docstrings` in the development environment of your choice to learn about the available properties as an alternative to consulting the online [Full Reference](/python/reference/).
91
-
71
+
2. Graph objects contain descriptions of each valid property as Python docstrings, with a [full API reference available](https://plotly.com/python-api-reference/). You can use these docstrings in the development environment of your choice to learn about the available properties as an alternative to consulting the online [Full Reference](/python/reference/).
92
72
3. Properties of graph objects can be accessed using both dictionary-style key lookup (e.g. `fig["layout"]`) or class-style property access (e.g. `fig.layout`).
73
+
4. Graph objects support higher-level convenience functions for making updates to already constructed figures (`.update_layout()`, `.add_trace()` etc) as described below.
74
+
5. Graph object constructors and update methods accept "magic underscores" (e.g. `go.Figure(layout_title_text="The Title")` rather than `dict(layout=dict(title=dict(text="The Title")))`) for more compact code, as described below.
75
+
6. Graph objects support attached rendering (`.show()`) and exporting functions (`.write_image()`) that automatically invoke the appropriate functions from [the `plotly.io` module](https://plotly.com/python-api-reference/plotly.io.html).
93
76
94
-
4. Graph objects support higher-level convenience functions for making updates to already constructed figures, as described below.
95
-
96
-
**Graph objects are stored in a hierarchy of modules under the `plotly.graph_objects` package, so make sure to remember to `import plotly.graph_objects as go` when you want to use them.**
97
77
98
78
Below you can find an example of one way that the figure in the example above could be specified using a graph object instead of a dictionary.
99
79
@@ -151,35 +131,38 @@ print("\n\n")
151
131
152
132
This section summarizes several ways to create new graph object figures with the `plotly.py` graphing library.
153
133
154
-
#### Graph Objects `Figure` Constructor
134
+
> The *recommended way* to create figures and populate them is to use [Plotly Express](/python/plotly-express/) but this page documents various other options for completeness
155
135
156
-
As demonstrated above, you can build a complete figure by passing trace and layout specifications to the `plotly.graph_objects.Figure` constructor. These trace and layout specifications can be either dictionaries or graph objects.
157
136
158
-
In the following example, the traces are specified using graph objects and the layout is specified as a dictionary.
137
+
#### Plotly Express
138
+
139
+
[Plotly Express](https://plot.ly/python/plotly-express/) (included as the `plotly.express` module) is a high-level data visualization API that produces fully-populated graph object figures in single function-calls.
159
140
160
141
```python
161
-
import plotly.graph_objectsasgo
142
+
import plotly.expressaspx
162
143
163
-
fig = go.Figure(
164
-
data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
165
-
layout=dict(title=dict(text="A Figure Specified By A Graph Object"))
# If you print the figure, you'll see that it's just a regular figure with data and layout
148
+
# print(fig)
167
149
168
150
fig.show()
169
151
```
170
152
171
-
#### Plotly Express
153
+
#### Graph Objects `Figure` Constructor
172
154
173
-
[Plotly Express](https://plot.ly/python/plotly-express/) (included as the `plotly.express` module) is a high-level data exploration API that produces graph object figures.
155
+
As demonstrated above, you can build a complete figure by passing trace and layout specifications to the `plotly.graph_objects.Figure` constructor. These trace and layout specifications can be either dictionaries or graph objects.
174
156
175
-
```python
176
-
import plotly.express as px
157
+
In the following example, the traces are specified using graph objects and the layout is specified as a dictionary.
0 commit comments