Merge branch 'master' into more_pandas

.gitignore

@@ -46,3 +46,4 @@ temp-plot.html
 doc/python/.ipynb_checkpoints
 doc/python/.mapbox_token
 doc/.ipynb_checkpoints
+doc/check-or-enforce-order.py

CHANGELOG.md

@@ -2,17 +2,34 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+
 ## [4.9.0] - unreleased
 
 ### Updated
 
 - Added all cartesian-2d Plotly Express functions, plus `imshow` to Pandas backend with `kind` option
+- `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))
+
+
+## [4.8.2] - 2020-06-26
+
+### Updated
+
+- 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.
+- `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!
 
-## [4.8.2] - unreleased
 
 ### Fixed
 
+- `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!
 - Fixed special cases with `px.sunburst` and `px.treemap` with `path` input ([#2524](https://github.com/plotly/plotly.py/pull/2524))
+- 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)).
+- 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))
+- 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))
+- Plotly Express wide mode now accepts mixed integer and float columns ([#2598](https://github.com/plotly/plotly.py/pull/2598))
+- Plotly Express `range_(x|y)` should not impact the unlinked range of marginal subplots ([#2600](https://github.com/plotly/plotly.py/pull/2600))
+- `px.line` now sets `line_group=<variable>` in wide mode by default ([#2599](https://github.com/plotly/plotly.py/pull/2599))
+- Corrected some regex warnings ([#2577](https://github.com/plotly/plotly.py/pull/2577)), with thanks to [@georgevdd](https://github.com/georgevdd) for the contribution!
 
 ## [4.8.1] - 2020-05-28
 

README.md

@@ -33,7 +33,7 @@
 
 ## Quickstart
 
-`pip install plotly==4.8.1`
+`pip install plotly==4.8.2`
 
 Inside [Jupyter notebook](https://jupyter.org/install) (installable with `pip install "notebook>=5.3" "ipywidgets>=7.2"`):
 
@@ -82,13 +82,13 @@ 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.8.1
+pip install plotly==4.8.2
 ```
 
 or conda.
 
 ```
-conda install -c plotly plotly=4.8.1
+conda install -c plotly plotly=4.8.2
 ```
 
 ### Jupyter Notebook Support
@@ -125,10 +125,10 @@ Then run the following commands to install the required JupyterLab extensions (n
 
 ```
 # Basic JupyterLab renderer support
-jupyter labextension install jupyterlab-plotly@4.8.1
+jupyter labextension install jupyterlab-plotly@4.8.2
 
 # OPTIONAL: Jupyter widgets extension for FigureWidget support
-jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.8.1
+jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.8.2
 ```
 
 Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.

binder/requirements.txt

@@ -1,5 +1,5 @@
 jupytext
-plotly==4.8.1
+plotly==4.8.2
 jupyter
 notebook
 pandas==1.0.3

contributing.md

@@ -64,7 +64,7 @@ the structure of the code and of the repository.
   https://github.com/plotly/plotly.py/issues/1965. If you have writing skills,
   the wording of existing examples can also be improved in places.
 
-Contributing code or documentation are not the only way to contribute! You can
+Contributing code or documentation is not the only way to contribute! You can
 also contribute to the project by
 
 - reporting bugs (see below).
@@ -151,7 +151,12 @@ complete installation and avoid gdal-config errors.
 ```
 This will ensure that the installed packages links to your local development
 directory, meaning that all changes you make reflect directly in your
-environment (don't forget to restart the Jupyter kernel though!).
+environment (don't forget to restart the Jupyter kernel though!). For more
+information see the
+[`setuptools`](https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode)
+and
+[`pip`](https://pip.pypa.io/en/stable/reference/pip_install/#install-editable)
+documentation on _development mode_.
 
 ### ipywidgets development install
 

doc/apidoc/conf.py

@@ -28,7 +28,7 @@
 # The short X.Y version
 version = ""
 # The full version, including alpha/beta/rc tags
-release = "4.8.1"
+release = "4.8.2"
 
 
 # -- General configuration ---------------------------------------------------

doc/apidoc/plotly.graph_objects.rst

@@ -43,6 +43,7 @@ Simple Traces
    Bar
    Pie
    Heatmap
+   Heatmapgl
    Image
    Contour
    Table

doc/python/3d-scatter-plots.md

@@ -76,7 +76,7 @@ fig.update_layout(margin=dict(l=0, r=0, b=0, t=0))
 
 #### Basic 3D Scatter Plot
 
-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`.
+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/).
 Like the [2D scatter plot](https://plotly.com/python/line-and-scatter/) `go.Scatter`, `go.Scatter3d` plots individual data in three-dimensional space.
 
 ```python

doc/python/animations.md

@@ -51,6 +51,12 @@ fig = px.bar(df, x="continent", y="pop", color="continent",
 fig.show()
 ```
 
+### Current Animation Limitations and Caveats
+
+* 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.
+* Although Plotly Express supports animation for many chart and map types, smooth inter-frame transitions are today only possible for scatter and bar
+* 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
+
 #### Animated figures with Graph Objects
 
 The remainder of this section describes the low-level API for constructing animated figures manually.

doc/python/axes.md

@@ -29,7 +29,7 @@ jupyter:
     language: python
     layout: base
     name: Axes
-    order: 12
+    order: 13
     permalink: python/axes/
     thumbnail: thumbnail/axes.png
 ---

doc/python/bar-charts.md

@@ -99,7 +99,7 @@ To learn more, see the _link to px.bar reference page_.
 
 #### Basic Bar Chart with plotly.graph_objects
 
-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`.
+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

doc/python/box-plots.md

@@ -134,7 +134,7 @@ fig.show()
 
 ## Box plot with go.Box
 
-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.
+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.
 
 ### Basic Box Plot
 

doc/python/bubble-charts.md

@@ -52,7 +52,7 @@ fig.show()
 
 ## Bubble Chart with plotly.graph_objects
 
-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.
+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.
 
 ### Simple Bubble Chart
 

doc/python/builtin-colorscales.md

@@ -30,7 +30,7 @@ jupyter:
     language: python
     layout: base
     name: Built-in Continuous Color Scales
-    order: 26
+    order: 27
     permalink: python/builtin-colorscales/
     thumbnail: thumbnail/heatmap_colorscale.jpg
     v4upgrade: true

doc/python/colorscales.md

@@ -30,7 +30,7 @@ jupyter:
     language: python
     layout: base
     name: Continuous Color Scales and Color Bars
-    order: 19
+    order: 20
     permalink: python/colorscales/
     redirect_from: python/logarithmic-color-scale/
     thumbnail: thumbnail/heatmap_colorscale.jpg

doc/python/configuration-options.md

@@ -28,7 +28,7 @@ jupyter:
     language: python
     layout: base
     name: Configuration
-    order: 8
+    order: 9
     page_type: u-guide
     permalink: python/configuration-options/
     thumbnail: thumbnail/modebar-icons.png

doc/python/creating-and-updating-figures.md

@@ -37,17 +37,13 @@ jupyter:
     v4upgrade: true
 ---
 
-### Representing Figures
+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.
 
-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.
+> 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.
 
-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.
+### Figures As Dictionaries
 
-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.
-
-#### Figures As Dictionaries
-
-The `fig` dictonary in the example below describes a figure. It contains a single `bar` trace and a title.
+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.
 
 ```python
 fig = dict({
@@ -63,37 +59,21 @@ import plotly.io as pio
 pio.show(fig)
 ```
 
-Let's take a closer look at structure of the `fig` dictionary in order to better understand how `plotly.py` figures are built.
-
-##### The `"data"` Key
-
-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.
-
-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.
-
-##### The `"layout"` Key
+### Figures as Graph Objects
 
-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.
+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`.
 
-The [_Full Reference_](https://plot.ly/python/reference/) page contains descriptions of all of the supported trace and layout attributes and configuration options.
+> 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/).
 
-If working from the _Full Reference_ to build figures as Python dictionaries and lists suites your needs, go for it!
-
-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`.
-
-#### Figures as Graph Objects
-
-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.
+Graph objects have several benefits compared to plain Python dictionaries.
 
 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.
-
-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/).
-
+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/).
 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`).
+4. Graph objects support higher-level convenience functions for making updates to already constructed figures (`.update_layout()`, `.add_trace()` etc) as described below.
+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.
+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).
 
-4. Graph objects support higher-level convenience functions for making updates to already constructed figures, as described below.
-
-**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.**
 
 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.
 
@@ -151,35 +131,38 @@ print("\n\n")
 
 This section summarizes several ways to create new graph object figures with the `plotly.py` graphing library.
 
-#### Graph Objects `Figure` Constructor
+> 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
 
-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.
 
-In the following example, the traces are specified using graph objects and the layout is specified as a dictionary.
+#### Plotly Express
+
+[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.
 
 ```python
-import plotly.graph_objects as go
+import plotly.express as px
 
-fig = go.Figure(
-    data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
-    layout=dict(title=dict(text="A Figure Specified By A Graph Object"))
-)
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", title="A Plotly Express Figure")
+
+# If you print the figure, you'll see that it's just a regular figure with data and layout
+# print(fig)
 
 fig.show()
 ```
 
-#### Plotly Express
+#### Graph Objects `Figure` Constructor
 
-[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.
+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.
 
-```python
-import plotly.express as px
+In the following example, the traces are specified using graph objects and the layout is specified as a dictionary.
 
-df = px.data.iris()
-fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", title="A Plotly Express Figure")
+```python
+import plotly.graph_objects as go
 
-# If you print fig, you'll see that it's just a regular figure with data and layout
-# print(fig)
+fig = go.Figure(
+    data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
+    layout=dict(title=dict(text="A Figure Specified By A Graph Object"))
+)
 
 fig.show()
 ```

doc/python/discrete-color.md

@@ -30,7 +30,7 @@ jupyter:
     language: python
     layout: base
     name: Discrete Colors
-    order: 27
+    order: 28
     permalink: python/discrete-color/
     thumbnail: thumbnail/heatmap_colorscale.jpg
     v4upgrade: true

doc/python/dropdowns.md

@@ -147,7 +147,7 @@ fig.update_scenes(
     aspectmode="manual"
 )
 
-# Add drowdowns
+# Add dropdowns
 button_layer_1_height = 1.08
 fig.update_layout(
     updatemenus=[

doc/python/figure-factories.md

@@ -28,7 +28,7 @@ jupyter:
     language: python
     layout: base
     name: Figure Factories
-    order: 31
+    order: 32
     permalink: python/figure-factories/
     thumbnail: thumbnail/streamline.jpg
 ---