Merge branch 'hover-format-or-skip' of https://github.com/plotly/plotly.py into hover-format-or-skip

Author: emmanuelle

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/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