documenting text_auto and deprecating FFs

plotly · nicolaskruchten · Dec 20, 2021 · Dec 15, 2021 · Dec 16, 2021 · Dec 16, 2021
commit 3214f9cfd5e98a011069c765da757777e82e446e
diff --git a/doc/python/2D-Histogram.md b/doc/python/2D-Histogram.md
@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.3'
       jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3 (ipykernel)
+    display_name: Python 3
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.11
+    version: 3.8.11
   plotly:
     description: How to make 2D Histograms in Python with Plotly.
     display_as: statistical
@@ -82,14 +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}")`
+### Displaying Text
+
+*New in v5.5*
+
+You can add the `z` values as text using the `text_auto` argument. Setting it to `True` will display the values on the bars, and setting it to a `d3-format` formatting string will control the output format.
 
 ```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 = px.density_heatmap(df, x="total_bill", y="tip", text_auto=True)
 fig.show()
 ```
 

diff --git a/doc/python/annotated-heatmap.md b/doc/python/annotated-heatmap.md
@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.3'
       jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3 (ipykernel)
+    display_name: Python 3
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.11
+    version: 3.8.11
   plotly:
     description: How to make Annotated Heatmaps in Python with Plotly.
     display_as: scientific
@@ -34,9 +34,11 @@ jupyter:
     thumbnail: thumbnail/ann_heat.jpg
 ---
 
-### Annotated Heatmaps with plotly.express and px.imshow
+### Annotated Heatmaps with Plotly Express
 
-These examples use [px.imshow](/python/imshow) to create Annotated Heatmaps. px.imshow is the recommended way to create heatmaps with z-annotations.
+*New in v5.5*
+
+As of version 5.5.0 of `plotly`, the **recommended way to [display annotated heatmaps is to use `px.imshow()`](/python/heatmaps/)** rather than the now-deprecated `create_annotated_heatmap` figure factory documented below for historical reasons.
 
 
 #### Basic Annotated Heatmap for z-annotations
@@ -46,33 +48,19 @@ After creating a figure with `px.imshow`, you can add z-annotations with `.updat
 ```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
-
-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})
+z = [[.1, .3, .5, .7, .9],
+     [1, .8, .6, .4, .2],
+     [.2, 0, .5, .7, .9],
+     [.9, .8, .4, .2, 0],
+     [.3, .4, .5, .7, 1]]
 
+fig = px.imshow(z, text_auto=True)
 fig.show()
 ```
 
-### Annotated Heatmaps with [figure factory](/python/figure-factories/). For more examples with Heatmaps, see [this page](/python/heatmaps/).
+### Deprecated Figure Factory
 
-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/).
+The remaining examples show how to create Annotated Heatmaps with the deprecated `create_annotated_heatmap` [figure factory](/python/figure-factories/).
 
 
 #### Simple Annotated Heatmap
@@ -90,54 +78,48 @@ fig = ff.create_annotated_heatmap(z)
 fig.show()
 ```
 
-#### Defined Colorscale
+#### Custom Text and X & Y Labels
+set `annotation_text` to a matrix with the same dimensions as `z`
+
+> WARNING: this legacy figure factory requires the `y` array to be provided in reverse order, and will map the `z_text` to the `z` values in reverse order. **The use of the `px.imshow()` version below is highly recommended**
 
 ```python
 import plotly.figure_factory as ff
 
-z = [[.1, .3, .5, .7],
-     [1, .8, .6, .4],
-     [.6, .4, .2, .0],
-     [.9, .7, .5, .3]]
-
-fig = ff.create_annotated_heatmap(z, colorscale='Viridis')
-fig.show()
-```
-
-#### Custom Colorscale
+z = [[.1, .3, .5],
+     [1.0, .8, .6],
+     [.6, .4, .2]]
 
-```python
-import plotly.figure_factory as ff
+x = ['Team A', 'Team B', 'Team C']
+y = ['Game Three', 'Game Two', 'Game One']
 
-z = [[.1, .3, .5, .7],
-     [1.0, .8, .6, .4],
-     [.6, .4, .2, 0.0],
-     [.9, .7, .5, .3]]
+z_text = [['Win', 'Lose', 'Win'],
+          ['Lose', 'Lose', 'Win'],
+          ['Win', 'Win', 'Lose']]
 
-colorscale = [[0, 'navy'], [1, 'plum']]
-font_colors = ['white', 'black']
-fig = ff.create_annotated_heatmap(z, colorscale=colorscale, font_colors=font_colors)
+fig = ff.create_annotated_heatmap(z, x=x, y=y, annotation_text=z_text, colorscale='Viridis')
 fig.show()
 ```
 
-#### Custom Text and X & Y Labels
-set `annotation_text` to a matrix with the same dimensions as `z`
+Here is the same figure using `px.imshow()`
 
 ```python
-import plotly.figure_factory as ff
+import plotly.express as px
+
+x = ['Team A', 'Team B', 'Team C']
+y = ['Game One', 'Game Two', 'Game Three']
 
 z = [[.1, .3, .5],
      [1.0, .8, .6],
      [.6, .4, .2]]
 
-x = ['Team A', 'Team B', 'Team C']
-y = ['Game Three', 'Game Two', 'Game One']
-
 z_text = [['Win', 'Lose', 'Win'],
           ['Lose', 'Lose', 'Win'],
           ['Win', 'Win', 'Lose']]
 
-fig = ff.create_annotated_heatmap(z, x=x, y=y, annotation_text=z_text, colorscale='Viridis')
+fig = px.imshow(z, x=x, y=y, color_continuous_scale='Viridis', aspect="auto")
+fig.update_traces(text=z_text, texttemplate="%{text}")
+fig.update_xaxes(side="top")
 fig.show()
 ```
 
@@ -161,82 +143,16 @@ for i in range(len(fig.layout.annotations)):
 fig.show()
 ```
 
-#### Custom Hovertext
+Here is the same figure using `px.imshow()`
 
 ```python
-# Add Periodic Table Data
-symbol = [['H', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', 'He'],
-         ['Li', 'Be', '', '', '', '', '', '', '', '', '', '', 'B', 'C', 'N', 'O', 'F', 'Ne'],
-         ['Na', 'Mg', '', '', '', '', '', '', '', '', '', '', 'Al', 'Si', 'P', 'S', 'Cl', 'Ar'],
-         ['K', 'Ca', 'Sc', 'Ti', 'V', 'Cr', 'Mn', 'Fe', 'Co', 'Ni', 'Cu', 'Zn', 'Ga', 'Ge', 'As', 'Se', 'Br', 'Kr'],
-         ['Rb ', 'Sr', 'Y', 'Zr', 'Nb', 'Mo', 'Tc', 'Ru', 'Rh', 'Pd', 'Ag', 'Cd', 'In', 'Sn', 'Sb', 'Te', 'I', 'Xe' ],
-         ['Cs', 'Ba', '', 'Hf', 'Ta', 'W', 'Re', 'Os', 'Ir', 'Pt', 'Au', 'Hg', 'Tl', 'Pb', 'Bi', 'Po', 'At', 'Rn' ],
-         ['Fr', 'Ra', '', 'Rf', 'Db', 'Sg', 'Bh', 'Hs', 'Mt', 'Ds', 'Rg', 'Cn', 'Uut', 'Fl', 'Uup', 'Lv', 'Uus', 'Uuo'],
-         ['', '', 'La', 'Ce', 'Pr', 'Nd', 'Pm', 'Sm', 'Eu', 'Gd', 'Tb', 'Dy', 'Ho', 'Er', 'Tm', 'Yb', 'Lu', ''],
-         ['', '', 'Ac', 'Th', 'Pa', 'U', 'Np', 'Pu', 'Am', 'Cm', 'Bk', 'Cf', 'Es', 'Fm', 'Md', 'No', 'Lr', '' ],
-         ['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', ''],
-         ['', 'Alkali Metal', '', '', 'Transition Metal', '', '', 'Actinide', '', '', 'Semimetal', '', '', 'Halogen', '', '', '', ''],
-         ['', 'Alkaline Metal', '', '', 'Lanthanide', '', '', 'Basic Metal', '', '', 'Nonmetal', '', '', 'Noble Gas', '', '', '', '']]
-
-element = [['Hydrogen', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', 'Helium'],
-           ['Lithium', 'Beryllium', '', '', '', '', '', '', '', '', '', '', 'Boron', 'Carbon', 'Nitrogen', 'Oxygen', 'Fluorine', 'Neon'],
-           ['Sodium', 'Magnesium', '', '', '', '', '', '', '', '', '', '', 'Aluminium', 'Silicon', 'Phosphorus', 'Sulfur', 'Chlorine', ' Argon'],
-           ['Potassium', ' Calcium', ' Scandium', ' Titanium', ' Vanadium', ' Chromium',  'Manganese', 'Iron', 'Cobalt', 'Nickel', 'Copper', 'Zinc', 'Gallium', 'Germanium', 'Arsenic', 'Selenium', 'Bromine', 'Krypton'],
-           ['Rubidium', 'Strontium', 'Yttrium', 'Zirconium', 'Niobium', 'Molybdenum', 'Technetium', 'Ruthenium', 'Rhodium', 'Palladium', 'Silver', 'Cadmium', 'Indium', 'Tin', 'Antimony', 'Tellurium', 'Iodine', 'Xenon'],
-           [' Cesium', ' Barium', '',  'Hafnium', 'Tantalum', 'Tungsten', 'Rhenium', 'Osmium', 'Iridium', 'Platinum', 'Gold', 'Mercury', 'Thallium', 'Lead', 'Bismuth', 'Polonium', 'Astatine', 'Radon'],
-           [' Francium', ' Radium', '', 'Rutherfordium','Dubnium','Seaborgium','Bohrium','Hassium','Meitnerium','Darmstadtium','Roentgenium','Copernicium','Ununtrium','Ununquadium','Ununpentium','Ununhexium','Ununseptium','Ununoctium'],
-           ['', '',  'Lanthanum', 'Cerium', 'Praseodymium', 'Neodymium', 'Promethium', 'Samarium', 'Europium', 'Gadolinium', 'Terbium', 'Dysprosium', 'Holmium', 'Erbium', 'Thulium', 'Ytterbium', 'Lutetium', ''],
-           ['', '', 'Actinium', 'Thorium', 'Protactinium', 'Uranium', 'Neptunium', 'Plutonium', 'Americium', 'Curium', 'Berkelium', 'Californium', 'Einsteinium','Fermium' ,'Mendelevium', 'Nobelium', 'Lawrencium', '' ],
-           ['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', ''],
-           ['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', ''],
-           ['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '']]
-
-atomic_mass = [[ 1.00794, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0,  4.002602],
-     [ 6.941, 9.012182, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0,  10.811, 12.0107, 14.0067, 15.9994, 18.9984032, 20.1797],
-     [ 22.98976928, 24.3050, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0,  26.9815386, 28.0855, 30.973762, 32.065, 35.453, 39.948],
-     [ 39.0983, 40.078, 44.955912, 47.867, 50.9415, 51.9961, 54.938045, 55.845, 58.933195, 58.6934, 63.546, 65.38, 69.723, 72.64, 74.92160, 78.96, 79.904, 83.798],
-     [ 85.4678, 87.62, 88.90585, 91.224, 92.90638, 95.96, 98, 101.07, 102.90550, 106.42, 107.8682, 112.411, 114.818, 118.710, 121.760, 127.60, 126.90447, 131.293],
-     [ 132.9054519, 137.327, .0, 178.49, 180.94788, 183.84, 186.207, 190.23, 192.217, 195.084, 196.966569, 200.59, 204.3833, 207.2, 208.98040, 209, 210, 222],
-     [223, 226, .0, 267, 268, 271, 272, 270, 276, 281, 280, 285, 284, 289, 288, 293, 'unknown', 294],
-     [.0, .0, 138.90547, 140.116, 140.90765, 144.242, 145, 150.36, 151.964, 157.25, 158.92535, 162.500, 164.93032, 167.259, 168.93421, 173.054, 174.9668, .0],
-     [.0, .0, 227, 232.03806, 231.03588, 238.02891, 237, 244, 243, 247, 247, 251, 252, 257, 258, 259, 262, .0],
-     [.0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0],
-     [.0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0],
-     [.0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0]]
-
-z = [[.8, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, 1.],
-     [.1, .2, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .7, .8, .8, .8, .9, 1.],
-     [.1, .2, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .6, .7, .8, .8, .9, 1],
-     [.1, .2, .3, .3, .3, .3, .3, .3, .3, .3, .3, .3, .6, .7, .8, .8, .9, 1.],
-     [.1, .2, .3, .3, .3, .3, .3, .3, .3, .3, .3, .3, .6, .6, .7, .7, .9, 1.],
-     [.1, .2, .4, .3, .3, .3, .3, .3, .3, .3, .3, .3, .6, .6, .6, .7, .9, 1.],
-     [.1, .2, .5, .3, .3, .3, .3, .3, .3, .3, .3, .3, .6, .6, .6, .6, .9, 1.],
-     [.0, .0, .4, .4, .4, .4, .4, .4, .4, .4, .4, .4, .4, .4, .4, .4, .4, .0],
-     [.0, .0, .5, .5, .5, .5, .5, .5, .5, .5, .5, .5, .5, .5, .5, .5, .5, .0],
-     [.0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0],
-     [.1, .1, .1, .3, .3, .3, .5, .5, .5, .7, .7, .7, .9, .9, .9, .0, .0, .0],
-     [.2, .2, .2, .4, .4, .4, .6, .6, .6, .8, .8, .8, 1., 1., 1., .0, .0, .0]]
-
-# Display element name and atomic mass on hover
-hover=[]
-for x in range(len(symbol)):
-    hover.append([i + '<br>' + 'Atomic Mass: ' + str(j)
-                      for i, j in zip(element[x], atomic_mass[x])])
-
-# Invert Matrices
-symbol = symbol[::-1]
-hover = hover[::-1]
-z = z[::-1]
-
-# Set Colorscale
-colorscale=[[0.0, 'rgb(255,255,255)'], [.2, 'rgb(255, 255, 153)'],
-            [.4, 'rgb(153, 255, 204)'], [.6, 'rgb(179, 217, 255)'],
-            [.8, 'rgb(240, 179, 255)'],[1.0, 'rgb(255, 77, 148)']]
-
-# Make Annotated Heatmap
-fig = ff.create_annotated_heatmap(z, annotation_text=symbol, text=hover,
-                                 colorscale=colorscale, font_colors=['black'], hoverinfo='text')
-fig.update_layout(title_text='Periodic Table')
+import plotly.express as px
+import numpy as np
+np.random.seed(1)
+
+z = np.random.randn(20, 20)
+
+fig = px.imshow(z, text_auto=".2f", color_continuous_scale='Greys', aspect="auto")
 fig.show()
 ```
 

diff --git a/doc/python/bar-charts.md b/doc/python/bar-charts.md
@@ -5,8 +5,8 @@ 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
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.8.11
   plotly:
     description: How to make Bar Charts in Python with Plotly.
     display_as: basic
@@ -98,7 +98,7 @@ snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
 IFrame(snippet_url + 'bar-charts', width='100%', height=630)
 ```
 
-### Customize bar charts with Plotly Express
+### Customized bar charts with Plotly Express
 
 The bar plot can be customized using keyword arguments, for example to use [continuous color](https://plotly.com/python/colorscales/), as below, or [discrete color](/python/discrete-color/), as above.
 
@@ -147,6 +147,20 @@ fig = px.bar(df, x="medal", y="count", color="nation",
 fig.show()
 ```
 
+#### Bar Charts with Text
+
+*New in v5.5*
+
+You can add text to bars using the `text_auto` argument. Setting it to `True` will display the values on the bars, and setting it to a `d3-format` formatting string will control the output format.
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation", text_auto=True)
+fig.show()
+```
+
 #### Facetted subplots
 
 Use the keyword arguments `facet_row` (resp. `facet_col`) to create facetted subplots, where different rows (resp. columns) correspond to different values of the dataframe column specified in `facet_row`.

diff --git a/doc/python/county-choropleth.md b/doc/python/county-choropleth.md
@@ -41,11 +41,12 @@ This page describes a [legacy "figure factory" method](/python/figure-factories/
 
 
 #### Required Packages
-`geopandas`, `pyshp` and `shapely` must be installed for this figure factory.
+`plotly_geo`, `pyshp` and `shapely` must be installed for this figure factory.
 
 Run the following commands to install the correct versions of the following modules:
 
 ```python
+!pip install plotly-geo
 !pip install geopandas==0.3.0
 !pip install pyshp==1.2.10
 !pip install shapely==1.6.3

diff --git a/doc/python/figure-factories.md b/doc/python/figure-factories.md
@@ -5,8 +5,8 @@ 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
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.8.11
   plotly:
     description: Figure Factories are dedicated functions for creating very specific
       types of plots.
@@ -39,7 +39,6 @@ The `plotly.figure_factory` module contains dedicated functions for creating ver
 
 The following types of plots are still difficult to create with Graph Objects or Plotly Express and therefore the corresponding Figure Factories are *not* deprecated:
 
-  * [Annotated Heatmaps](/python/annotated-heatmap/)
   * [Dendrograms](/python/dendrogram/)
   * [Hexagonal Binning Tile Map](/python/hexbin-mapbox/)
   * [Quiver Plots](/python/quiver-plots/)
@@ -50,10 +49,15 @@ The following types of plots are still difficult to create with Graph Objects or
 
 Deprecated "legacy" Figure Factories include:
 
+  * [Annotated Heatmaps](/python/annotated-heatmap/), deprecated by [heatmaps with `px.imshow()`](/python/heatmaps/)
   * [County Choropleth Maps](/python/county-choropleth/), deprecated by regular [Choropleth maps with GeoJSON input](/python/choropleth-maps/)
   * [Distplots](/python/distplot/), mostly deprecated by [`px.histogram`](/python/histograms/) except for KDE plots, which `px.histogram` doesn't support yet
   * [Gantt Charts](/python/gantt/), deprecated by [`px.timeline`](/python/gantt/)
 
 #### Reference
 
 For more information about the contents of `plotly.figure_factory`, including deprecated methods, please refer to our [API Reference documentation](https://plotly.com/python-api-reference/plotly.figure_factory.html).
+
+```python
+
+```
diff --git a/doc/python/heatmaps.md b/doc/python/heatmaps.md
@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.3'
       jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3 (ipykernel)
+    display_name: Python 3
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.11
+    version: 3.8.11
   plotly:
     description: How to make Heatmaps in Python with Plotly.
     display_as: scientific
@@ -34,11 +34,25 @@ jupyter:
     thumbnail: thumbnail/heatmap.jpg
 ---
 
-### Heatmap with `plotly.express` and `px.imshow`
+The term "heatmap" usually refers to a cartesian plot with data visualized as colored rectangular tiles, which is the subject of this page. It is also sometimes used to refer to [actual maps with density data displayed as color intensity](/python/mapbox-density-heatmaps/).
+
+Plotly supports two different types of colored-tile heatmaps:
+
+1. **Matrix Heatmaps** accept a 2-dimensional matrix or array of data and visualizes it directly. This type of heatmap is the subject of this page.
+2. **Density Heatmaps** accept data as a list and visualizes aggregated quantities like counts or sums of this data. Please refer to the [2D Histogram documentation](/python/2D-Histogram/) for this kind of figure.
+
+
+### Heatmaps with Plotly Express
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.imshow`, each value of the input array or data frame is represented as a heatmap pixel.
 
-For more examples using `px.imshow`, see the [tutorial on displaying image data with plotly](/python/imshow).
+
+<!-- #region -->
+The `px.imshow()` can be used to display heatmaps (as well as full-color images, as its name suggests). It accepts both array-like objects like lists of lists and `numpy` or `xarray` arrays, as well as `pandas.DataFrame` objects.
+
+
+> For more examples using `px.imshow`, including examples of faceting and animations, as well as full-color image display, see the [the `imshow` documentation page](/python/imshow).
+<!-- #endregion -->
 
 ```python
 import plotly.express as px
@@ -57,6 +71,28 @@ fig = px.imshow(df)
 fig.show()
 ```
 
+<!-- #region -->
+### Displaying Text on Heatmaps
+
+*New in v5.5*
+
+
+You can add the values to the figure as text using the `text_auto` argument. Setting it to `True` will display the values on the bars, and setting it to a `d3-format` formatting string will control the output format.
+<!-- #endregion -->
+
+```python
+import plotly.express as px
+
+z = [[.1, .3, .5, .7, .9],
+     [1, .8, .6, .4, .2],
+     [.2, 0, .5, .7, .9],
+     [.9, .8, .4, .2, 0],
+     [.3, .4, .5, .7, 1]]
+
+fig = px.imshow(z, text_auto=True)
+fig.show()
+```
+
 #### Heatmaps in Dash
 
 [Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
@@ -70,6 +106,23 @@ snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
 IFrame(snippet_url + 'heatmaps', width='100%', height=630)
 ```
 
+### Controlling Aspect Ratio
+
+By default, `px.imshow()` produces heatmaps with square tiles, but setting the `aspect` argument to `"auto"` will instead fill the plotting area with the heatmap, using non-square tiles.
+
+```python
+import plotly.express as px
+
+z = [[.1, .3, .5, .7, .9],
+     [1, .8, .6, .4, .2],
+     [.2, 0, .5, .7, .9],
+     [.9, .8, .4, .2, 0],
+     [.3, .4, .5, .7, 1]]
+
+fig = px.imshow(z, text_auto=True, aspect="auto")
+fig.show()
+```
+
 ### Customizing the axes and labels on a heatmap
 
 You can use the `x`, `y` and `labels` arguments to customize the display of a heatmap, and use `.update_xaxes()` to move the x axis tick labels to the top:
@@ -86,18 +139,16 @@ fig.update_xaxes(side="top")
 fig.show()
 ```
 
-### Adding and customizing text on points
+### Display an xarray image with px.imshow
 
-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`.
+[xarrays](http://xarray.pydata.org/en/stable/) are labeled arrays (with labeled axes and coordinates). If you pass an xarray image to `px.imshow`, its axes labels and coordinates will be used for axis titles. If you don't want this behavior, you can pass `img.values` which is a NumPy array if `img` is an xarray. Alternatively, you can override axis titles hover labels and colorbar title using the `labels` attribute, as above.
 
 ```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})
-
+import xarray as xr
+# Load xarray from dataset included in the xarray tutorial
+airtemps = xr.tutorial.open_dataset('air_temperature').air.sel(lon=250.0)
+fig = px.imshow(airtemps.T, color_continuous_scale='RdBu_r', origin='lower')
 fig.show()
 ```
 

diff --git a/doc/python/histograms.md b/doc/python/histograms.md
@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.3'
       jupytext_version: 1.13.4
   kernelspec:
-    display_name: Python 3 (ipykernel)
+    display_name: Python 3
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.11
+    version: 3.8.11
   plotly:
     description: How to make Histograms in Python with Plotly.
     display_as: statistical
@@ -208,15 +208,16 @@ fig = px.histogram(df, x="total_bill", color="sex", marginal="rug", # can be `bo
 fig.show()
 ```
 
-### Adding bar text
+### Adding text labels
 
-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. 
+*New in v5.5*
+
+You can add text to histogram bars using the `text_auto` argument. Setting it to `True` will display the values on the bars, and setting it to a `d3-format` formatting string will control the output format.
 
 ```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 = px.histogram(df, x="total_bill", y="tip", histfunc="avg", nbins=8, text_auto=True)
 fig.show()
 ```
 

diff --git a/packages/python/plotly/plotly/express/_core.py b/packages/python/plotly/plotly/express/_core.py
@@ -1794,8 +1794,10 @@ def infer_config(args, constructor, trace_patch, layout_patch):
     if args.get("text_auto", False) is not False:
         if constructor in [go.Histogram2d, go.Histogram2dContour]:
             letter = "z"
-        else:
+        elif constructor == go.Bar:
             letter = "y" if args["orientation"] == "v" else "x"
+        else:
+            letter = "value"
         if args["text_auto"] is True:
             trace_patch["texttemplate"] = "%{" + letter + "}"
         else:

diff --git a/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py b/packages/python/plotly/plotly/figure_factory/_annotated_heatmap.py
@@ -59,6 +59,9 @@ def create_annotated_heatmap(
     **kwargs
 ):
     """
+    **deprecated**, use instead
+    :func:`plotly.express.imshow`.
+
     Function that creates annotated heatmaps
 
     This function adds annotations to each cell of the heatmap.

diff --git a/packages/python/plotly/plotly/figure_factory/_county_choropleth.py b/packages/python/plotly/plotly/figure_factory/_county_choropleth.py
@@ -414,6 +414,11 @@ def create_choropleth(
     **layout_options
 ):
     """
+    **deprecated**, use instead
+    :func:`plotly.express.choropleth` with custom GeoJSON.
+
+    This function also requires `shapely`, `geopandas` and `plotly-geo` to be installed.
+
     Returns figure for county choropleth. Uses data from package_data.
 
     :param (list) fips: list of FIPS values which correspond to the con

diff --git a/packages/python/plotly/plotly/figure_factory/_gantt.py b/packages/python/plotly/plotly/figure_factory/_gantt.py
@@ -819,6 +819,9 @@ def create_gantt(
     show_hover_fill=True,
 ):
     """
+    **deprecated**, use instead
+    :func:`plotly.express.timeline`.
+
     Returns figure for a gantt chart
 
     :param (array|list) df: input data for gantt chart. Must be either a