Merge pull request #2362 from plotly/px_density_docs

Px density docs

Author: nicolaskruchten

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
@@ -33,6 +33,69 @@ jupyter:
     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