Sync Fork from Upstream Repo

.circleci/create_conda_optional_env.sh

@@ -16,7 +16,7 @@ if [ ! -d $HOME/miniconda/envs/circle_optional ]; then
     # Create environment
     # PYTHON_VERSION=2.7 or 3.5
     $HOME/miniconda/bin/conda create -n circle_optional --yes python=$PYTHON_VERSION \
-requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython jupyter ipykernel ipywidgets
+requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython jupyter ipykernel ipywidgets statsmodels
 
     # Install orca into environment
     $HOME/miniconda/bin/conda install --yes -n circle_optional -c plotly plotly-orca==1.3.1

.github/pull_request_template.md

@@ -32,5 +32,6 @@ below :-).
   modified existing tests.
 - [ ] For a new feature, I have added documentation examples in an existing or
   new tutorial notebook (please see the doc checklist as well).
+- [ ] I have added a CHANGELOG entry if fixing/changing/adding anything substantial.
 
 -->

CHANGELOG.md

@@ -2,6 +2,32 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Dev version
+
+To add:
+* https://github.com/plotly/plotly.py/pull/2349
+* https://github.com/plotly/plotly.py/pull/2357
+* https://github.com/plotly/plotly.py/pull/2419
+
+### Updated
+
+- Updated Plotly.js to version 1.54.0. The main feature of the Plotly.js is the
+  possibility to draw layout shapes, using custom dragmodes and corresponding
+  modebar buttons.
+
+### Added
+
+- The `hover_data` parameter of `px` functions can now be a dictionary. This
+  makes it possible to skip hover information for some arguments or to change  
+  the formatting of hover informatiom [#2377](https://github.com/plotly/plotly.py/pull/2377).
+
+### Performance
+This version includes several performance improvements ([#2368](https://github.com/plotly/plotly.py/pull/2368), [#2403](https://github.com/plotly/plotly.py/pull/2403)).
+
+ - Child graph objects (e.g. `figure.layout.xaxis`) are no longer created eagerly during graph object construction. Instead, they are created lazily the first time the property is accessed.
+ - Property validation is now disabled for select internal operations.
+ - When used with Python 3.7 and above, ploty.py now takes advantage of [PEP-562](https://www.python.org/dev/peps/pep-0562/) to perform submodule imports lazily.  This dramatically improves import times.
+
 ## [4.6] - 2020-03-31
 
 ### Updated

binder/requirements.txt

@@ -1,5 +1,5 @@
 jupytext
-plotly==4.5.4
+plotly==4.6.0
 jupyter
 notebook
 pandas

contributing.md

@@ -1,15 +1,15 @@
 # Contributing
 
 Thank you for contributing to plotly.py! We are actively looking for
-diverse contributors, with diverse background and skills. 
+diverse contributors, with diverse background and skills.
 
 This guide start by a general description of the different ways to contribute
 to plotly.py, then we explain some technical aspects of preparing your
-contribution. 
+contribution.
 
 ## Code of Conduct
 
-Please check out the [Code of Conduct](CODE_OF_CONDUCT.md). Don't tl:dr; it, 
+Please check out the [Code of Conduct](CODE_OF_CONDUCT.md). Don't tl:dr; it,
 but the general idea is to be nice.
 
 ## What are the different ways to contribute?
@@ -37,7 +37,7 @@ the structure of the code and of the repository.
 - the `plotly.figure_factory` module provides Python "recipes" for building
   advanced visualizations, such as Gantt charts, annotated heatmaps, etc.
   Figure factories are one of the easiest entry points into plotly.py, since
-  they consist of Python-only code, with standalone, well-separated functions. 
+  they consist of Python-only code, with standalone, well-separated functions.
   However, please note that some of the figure factories become less relevant
   as we are introducing more features into `plotly.express`. Some issues in the
   tracker are labeled "figure_factory" and can be good issues to work on. More
@@ -70,14 +70,14 @@ also contribute to the project by
 - reporting bugs (see below).
 
 - submitting feature requests (maybe we'll convince you to contribute it as a
-  pull request!). 
+  pull request!).
 
 - helping other users on the [community forum](https://community.plot.ly/).
   Join the list of [nice people](https://community.plot.ly/u) helping other
   plotly users :-).
 
 We also recommend reading the great
-[how to contribute to open source](https://opensource.guide/how-to-contribute/) 
+[how to contribute to open source](https://opensource.guide/how-to-contribute/)
 guide.
 
 ## Have a Bug Report?
@@ -98,7 +98,7 @@ Below we explain the technical aspects of contributing. It is not strictly neces
 
 Note that if you are modifying a single documentation page, you can do it
 directly on Github by clicking on the "Edit this page on GitHub" link, without
-cloning the repository. 
+cloning the repository.
 
 ## Setup a Development Environment
 
@@ -206,6 +206,7 @@ First update the version of the `plotly.js` dependency in `packages/javascript/p
 Then run the `updateplotlyjs` command with:
 
 ```bash
+$ cd packages/python/plotly
 $ python setup.py updateplotlyjs
 ```
 
@@ -214,6 +215,13 @@ the `plotly/plotly.js` GitHub repository (and place them in
 `plotly/package_data`). It will then regenerate all of the `graph_objs`
 classes based on the new schema.
 
+For dev branches, it is also possible to use `updateplotlyjsdev --devrepo reponame --devbranch branchname` to update to development versions of `plotly.js`. This will fetch the `plotly.js` in the CircleCI artifact of the branch `branchname` of the repo `reponame`. If `--devrepo` or `--devbranch` are omitted, `updateplotlyjsdev` defaults using `plotly/plotly.js` and `master` respectively. For example, to update to a version from a pull request to the `plotly/plotly.js` repo that is numbered 555, run:
+
+```bash
+$ cd packages/python/plotly
+$ python setup.py updateplotlyjsdev --devbranch pull/555
+```
+
 ## Testing
 
 We take advantage of two tools to run tests:

doc/apidoc/Makefile

@@ -18,9 +18,15 @@ help:
 # For sphinx-apidoc the first positional path is the module to document
 # then all the other ones are paths to exclude for the doc generation
 %: Makefile
+	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*.py
+	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*.py
+	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*/*.py
+	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*/*/*.py
 	sphinx-apidoc -o generated ../../packages/python/plotly/plotly ../../packages/python/plotly/plotly/validators ../../packages/python/plotly/plotly/tests ../../packages/python/plotly/plotly/matplotlylib/ ../../packages/python/plotly/plotly/offline ../../packages/python/plotly/plotly/api
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	git checkout -- ../../packages/python/plotly/plotly/graph_objs
 	rename 's/graph_objs/graph_objects/' _build/html/*.html _build/html/generated/*.html
+	mv _build/html/generated/plotly.graph_objs.html _build/html/generated/plotly.graph_objects.html
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.html 
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.inv 
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.js 

doc/apidoc/_templates/trace.rst

@@ -15,9 +15,9 @@
 
 .. autosummary::
 
-   plotly.graph_objects.{{ objname.lower() }}
+   plotly.graph_objs.{{ objname.lower() }}
 
-.. automodule:: plotly.graph_objects.{{ objname.lower() }}
+.. automodule:: plotly.graph_objs.{{ objname.lower() }}
    :members:
    :undoc-members:
 

doc/apidoc/conf.py

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

doc/python/2D-Histogram.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.0
+      jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.5
+    version: 3.6.8
   plotly:
     description: How to make 2D Histograms in Python with Plotly.
     display_as: statistical
@@ -30,9 +30,75 @@ jupyter:
     order: 6
     page_type: u-guide
     permalink: python/2D-Histogram/
+    redirect_from:
+      - python/2d-histogram/
+      - python/2d-histograms/
     thumbnail: thumbnail/histogram2d.jpg
 ---
 
+## 2D Histograms or Density Heatmaps
+
+A 2D histogram, also known as a density heatmap, is the 2-dimensional generalization of a [histogram](/python/histograms/) which resembles a [heatmap](/python/heatmaps/) but is computed by grouping a set of points specified by their `x` and `y` coordinates into bins, and applying an aggregation function such as `count` or `sum` (if `z` is provided) to compute the color of the tile representing the bin. This kind of visualization (and the related [2D histogram contour, or density contour](https://plotly.com/python/2d-histogram-contour/)) is often used to manage over-plotting, or situations where showing large data sets as [scatter plots](/python/line-and-scatter/) would result in points overlapping each other and hiding patterns. For data sets of more than a few thousand points, a better approach than the ones listed here would be to [use Plotly with Datashader](/python/datashader/) to precompute the aggregations before displaying the data with Plotly.
+
+## Density Heatmaps with Plotly Express
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). The Plotly Express function `density_heatmap()` can be used to produce density heatmaps.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_heatmap(df, x="total_bill", y="tip")
+fig.show()
+```
+
+The number of bins can be controlled with `nbinsx` and `nbinsy` and the [color scale](/python/colorscales/) with `color_continuous_scale`.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_heatmap(df, x="total_bill", y="tip", nbinsx=20, nbinsy=20, color_continuous_scale="Viridis")
+fig.show()
+```
+
+Marginal plots can be added to visualize the 1-dimensional distributions of the two variables. Here we use a marginal [`histogram`](/python/histograms/). Other allowable values are `violin`, `box` and `rug`.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_heatmap(df, x="total_bill", y="tip", marginal_x="histogram", marginal_y="histogram")
+fig.show()
+```
+
+Density heatmaps can also be [faceted](/python/facet-plots/):
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_heatmap(df, x="total_bill", y="tip", facet_row="sex", facet_col="smoker")
+fig.show()
+```
+
+### Other aggregation functions than `count`
+
+By passing in a `z` value and a `histfunc`, density heatmaps can perform basic aggregation operations. Here we show average Sepal Length grouped by Petal Length and Petal Width for the Iris dataset.
+
+```python
+import plotly.express as px
+df = px.data.iris()
+
+fig = px.density_heatmap(df, x="petal_length", y="petal_width", z="sepal_length", histfunc="avg")
+fig.show()
+```
+
+### 2D Histograms with Graph Objects
+
+To build this kind of plot without using Plotly Express, we can use the `go.Histogram2d` class.
+
+
 ### 2D Histogram of a Bivariate Normal Distribution ###
 
 ```python

doc/python/2d-histogram-contour.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.6.8
   plotly:
     description: How to make 2D Histogram Contour plots in Python with Plotly.
     display_as: statistical
@@ -30,9 +30,73 @@ jupyter:
     order: 12
     page_type: u-guide
     permalink: python/2d-histogram-contour/
+    redirect_from: python/2d-density-plots/
     thumbnail: thumbnail/hist2dcontour.png
 ---
 
+## 2D Histogram Contours or Density Contours
+
+A 2D histogram contour plot, also known as a density contour plot, is a 2-dimensional generalization of a [histogram](/python/histograms/) which resembles a [contour plot](/python/contour-plots/) but is computed by grouping a set of points specified by their `x` and `y` coordinates into bins, and applying an aggregation function such as `count` or `sum` (if `z` is provided) to compute the value to be used to compute contours. This kind of visualization (and the related [2D histogram, or density heatmap](/python/2d-histogram/)) is often used to manage over-plotting, or situations where showing large data sets as [scatter plots](/python/line-and-scatter/) would result in points overlapping each other and hiding patterns.
+
+## Density Contours with Plotly Express
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). The Plotly Express function `density_contour()` can be used to produce density contours.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_contour(df, x="total_bill", y="tip")
+fig.show()
+```
+
+Marginal plots can be added to visualize the 1-dimensional distributions of the two variables. Here we use a marginal [`histogram`](/python/histograms/). Other allowable values are `violin`, `box` and `rug`.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_contour(df, x="total_bill", y="tip", marginal_x="histogram", marginal_y="histogram")
+fig.show()
+```
+
+Density contours can also be [faceted](/python/facet-plots/) and [discretely colored](/python/discrete-color/):
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_contour(df, x="total_bill", y="tip", facet_col="sex", color="smoker")
+fig.show()
+```
+
+Plotly Express density contours can be [continuously-colored](/python/colorscales/) and labeled:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_contour(df, x="total_bill", y="tip")
+fig.update_traces(contours_coloring="fill", contours_showlabels = True)
+fig.show()
+```
+
+### Other aggregation functions than `count`
+
+By passing in a `z` value and a `histfunc`, density contours can perform basic aggregation operations. Here we show average Sepal Length grouped by Petal Length and Petal Width for the Iris dataset.
+
+```python
+import plotly.express as px
+df = px.data.iris()
+
+fig = px.density_contour(df, x="petal_length", y="petal_width", z="sepal_length", histfunc="avg")
+fig.show()
+```
+
+### 2D Histograms with Graph Objects
+
+To build this kind of plot without using Plotly Express, we can use the `go.Histogram2d` class.
+
 #### Basic 2D Histogram Contour
 
 ```python

doc/python/animations.md

@@ -261,18 +261,6 @@ fig_dict = {
 fig_dict["layout"]["xaxis"] = {"range": [30, 85], "title": "Life Expectancy"}
 fig_dict["layout"]["yaxis"] = {"title": "GDP per Capita", "type": "log"}
 fig_dict["layout"]["hovermode"] = "closest"
-fig_dict["layout"]["sliders"] = {
-    "args": [
-        "transition", {
-            "duration": 400,
-            "easing": "cubic-in-out"
-        }
-    ],
-    "initialValue": "1952",
-    "plotlycommand": "animate",
-    "values": years,
-    "visible": True
-}
 fig_dict["layout"]["updatemenus"] = [
     {
         "buttons": [