Merge pull request #3514 from plotly/dec-new-features-docs

New features docs - Dec

Author: nicolaskruchten

Diff for: doc/python/2D-Histogram.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.3.1
+      format_version: '1.3'
+      jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.7.11
   plotly:
     description: How to make 2D Histograms in Python with Plotly.
     display_as: statistical
@@ -82,6 +82,17 @@ fig = px.density_heatmap(df, x="total_bill", y="tip", facet_row="sex", facet_col
 fig.show()
 ```
 
+You can add the `z` values as text to 2D Histogram points using `fig.update_traces(texttemplate="%{z}")`
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.density_heatmap(df, x="total_bill", y="tip")
+fig.update_traces(texttemplate="%{z}") 
+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.
@@ -235,5 +246,24 @@ fig.update_layout(
 fig.show()
 ```
 
+### Text on 2D Histogram Points
+
+In this example we add text to 2D Histogram points. We use the values from the `z` attribute for the text.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.tips()
+
+fig = go.Figure(go.Histogram2d(
+        x=df.total_bill,
+        y=df.tip,
+        texttemplate= "%{z}"
+    ))
+
+fig.show()
+```
+
 #### Reference
 See https://plotly.com/python/reference/histogram2d/ for more information and chart attribute options!

Diff for: doc/python/annotated-heatmap.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.3'
+      jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.7.11
   plotly:
     description: How to make Annotated Heatmaps in Python with Plotly.
     display_as: scientific
@@ -34,9 +34,48 @@ jupyter:
     thumbnail: thumbnail/ann_heat.jpg
 ---
 
-#### Simple Annotated Heatmap
+### Annotated Heatmaps with plotly.express and px.imshow
+
+These examples use [px.imshow](/python/imshow) to create Annotated Heatmaps. px.imshow is the recommended way to create heatmaps with z-annotations.
+
+
+#### Basic Annotated Heatmap for z-annotations
+
+After creating a figure with `px.imshow`, you can add z-annotations with `.update_traces(texttemplate="%{z}")`.
+
+```python
+import plotly.express as px
+
+df = px.data.medals_wide(indexed=True)
+
+fig = px.imshow(df)
+fig.update_traces(texttemplate="%{z}")
+
+fig.show()
+```
+
+#### Custom Font
 
-This page details the use of a [figure factory](/python/figure-factories/). For more examples with Heatmaps, see [this page](/python/heatmaps/).
+You can make changes to the font using `textfont`. Here we set the font size to 20.
+
+```python
+import plotly.express as px
+
+df = px.data.medals_wide(indexed=True)
+
+fig = px.imshow(df)
+fig.update_traces(texttemplate="%{z}")
+fig.update_traces(textfont={"size":20})
+
+fig.show()
+```
+
+### Annotated Heatmaps with [figure factory](/python/figure-factories/). For more examples with Heatmaps, see [this page](/python/heatmaps/).
+
+The remaining examples show how to create Annotated Heatmaps with [figure factory](/python/figure-factories/). For more examples with Heatmaps, see [this page](/python/heatmaps/).
+
+
+#### Simple Annotated Heatmap
 
 ```python
 import plotly.figure_factory as ff

Diff for: doc/python/colorscales.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.6.0
+      format_version: '1.3'
+      jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,10 +20,10 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.6
+    version: 3.7.11
   plotly:
-    description: How to set, create and control continuous color scales and color bars
-      in scatter, bar, map and heatmap figures.
+    description: How to set, create and control continuous color scales and color
+      bars in scatter, bar, map and heatmap figures.
     display_as: file_settings
     has_thumbnail: true
     ipynb: ~notebook_demo/187
@@ -518,6 +518,31 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
+### Color Bar Displayed Horizontally
+
+By default, color bars are displayed vertically. You can change a color bar to be displayed horizontally by setting the `colorbar` `orientation` attribute to `h`.
+
+```python
+import plotly.graph_objects as go
+
+import six.moves.urllib
+import json
+
+# Load heatmap data
+response = six.moves.urllib.request.urlopen(
+    "https://raw.githubusercontent.com/plotly/datasets/master/custom_heatmap_colorscale.json")
+dataset = json.load(response)
+
+# Create and show figure
+fig = go.Figure()
+
+fig.add_trace(go.Heatmap(
+    z=dataset["z"],
+    colorbar=dict(orientation='h')))
+
+fig.show()
+```
+
 ### Sharing a Color Axis with Graph Objects
 
 To share colorscale information in multiple subplots, you can use [coloraxis](https://plotly.com/javascript/reference/scatter/#scatter-marker-line-coloraxis).

Diff for: doc/python/heatmaps.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.6.0
+      format_version: '1.3'
+      jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.6
+    version: 3.7.11
   plotly:
     description: How to make Heatmaps in Python with Plotly.
     display_as: scientific
@@ -86,6 +86,21 @@ fig.update_xaxes(side="top")
 fig.show()
 ```
 
+### Adding and customizing text on points
+
+You can add text to heatmap points with `.update_traces(texttemplate="%{variable}")`. Here we use the values of the `z` attribute for `variable`. We also customize the font size with `textfont`.
+
+```python
+import plotly.express as px
+
+df = px.data.medals_wide(indexed=True)
+fig = px.imshow(df)
+fig.update_traces(texttemplate="%{z}")
+fig.update_traces(textfont={"size":20})
+
+fig.show()
+```
+
 ### Basic Heatmap with `plotly.graph_objects`
 
 If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Heatmap` class from `plotly.graph_objects`](/python/graph-objects/).
@@ -197,6 +212,26 @@ fig.update_layout(
 fig.show()
 ```
 
+### Text on Heatmap Points
+
+In this example we add text to heatmap points using `texttemplate`. We use the values from the `text` attribute for the text. We also adjust the font size using `textfont`.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(data=go.Heatmap(
+                    z=[[1, 20, 30],
+                      [20, 1, 60],
+                      [30, 60, 1]],
+                    text=[['one', 'twenty', 'thirty'],
+                          ['twenty', 'one', 'sixty'],
+                          ['thirty', 'sixty', 'one']],
+                    texttemplate="%{text}",
+                    textfont={"size":20}))
+
+fig.show()
+```
+
 ### Heatmap and datashader
 
 Arrays of rasterized values build by datashader can be visualized using

Diff for: doc/python/histograms.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.7.11
   plotly:
     description: How to make Histograms in Python with Plotly.
     display_as: statistical
@@ -208,6 +208,18 @@ fig = px.histogram(df, x="total_bill", color="sex", marginal="rug", # can be `bo
 fig.show()
 ```
 
+### Adding bar text
+
+You can add text to histogram bars using `fig.update_traces(texttemplate="%{variable}")`, where `variable` is the text to add. In this example, we add the y-axis values to the bars. 
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.histogram(df, x="total_bill", y="tip", histfunc='avg', nbins=8)
+fig.update_traces(texttemplate="%{y}")
+fig.show()
+```
+
 ## Histograms with go.Histogram
 
 If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Histogram` class from `plotly.graph_objects`](/python/graph-objects/). All of the available histogram options are described in the histogram section of the reference page: https://plotly.com/python/reference#histogram.
@@ -340,6 +352,21 @@ fig.update_layout(
 fig.show()
 ```
 
+### Histogram Bar Text
+
+You can add text to histogram bars using the `texttemplate` argument. In this example we add the x-axis values as text following the format `%{variable}`. We also adjust the size of the text using `textfont_size`.
+
+```python
+import plotly.graph_objects as go
+
+numbers = ["5", "10", "3", "10", "5", "8", "5", "5"]
+
+fig = go.Figure()
+fig.add_trace(go.Histogram(x=numbers, name="count", texttemplate="%{x}", textfont_size=20))
+
+fig.show()
+```
+
 ### Cumulative Histogram
 
 ```python