Merge branch 'master' into periodic-table-example

Author: janosh

Diff for: .github/ISSUE_TEMPLATE.md

@@ -1,9 +1,7 @@
-Thanks for your interest in plotly.py!!
+Thanks for your interest in Plotly.py!
 
-Before opening an issue, please search for existing and closed issues. If your problem or idea is not addressed yet, [please open a new issue](https://github.com/plotly/plotly.py/issues/new).
+Before opening an issue, please search for existing and closed issues :)
 
-Bug reports **must** be accompanied with a reproducible example. Please use the [latest version](https://github.com/plotly/plotly.py/blob/master/CHANGELOG.md) of plotly.py in your report unless not applicable and specify if you're plotting [online](https://plot.ly/python/getting-started/#initialization-for-online-plotting) or [offline](https://plot.ly/python/getting-started/#initialization-for-offline-plotting).
+**Please** accompany bug reports with a reproducible example. Please use the [latest version](https://github.com/plotly/plotly.py/blob/master/CHANGELOG.md) of plotly.py in your report unless not applicable.
 
-Note that GitHub issues are reserved for bug reports and feature requests only. Implementation questions should be asked on community.plot.ly (tagged [`python`](https://community.plot.ly/c/api/python)) or on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).
-
-Comments on GitHub issues or pull requests should add content to the discussions. Approbation comments such as *+1* or *I would like this feature to be implemented as well* will be deleted by the maintainers. Please use [GitHub reactions](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments) instead.
+Note that GitHub Issues are meant to be used for bug reports and feature requests only. Implementation or usage questions should be asked on [community.plotly.com](https://community.plotly.com/c/graphing-libraries/python/10) or on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).

Diff for: CHANGELOG.md

@@ -2,6 +2,20 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## UNRELEASED
+
+### Added
+
+  - `text_auto` argument to `px.bar`, `px.histogram`, `px.density_heatmap`, `px.imshow` [#3518](https://github.com/plotly/plotly.py/issues/3518)
+  - Deprecated `ff.create_annotated_heatmap`, `ff.create_county_choropleth`, `ff.create_gantt` [#3518](https://github.com/plotly/plotly.py/issues/3518)
+
+### Updated
+  - Updated Plotly.js to from version 2.6.3 to version 2.8.1. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#280----2021-12-10) for more information. Notable changes include:
+    - Horizontal color bars
+    - texttemplate for histogram-like traces
+    - text for heatmap-like traces
+
+
 ## [5.4.0] - 2021-11-15
 
 ### Fixed

Diff for: doc/python/2D-Histogram.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: How to make 2D Histograms in Python with Plotly.
     display_as: statistical
@@ -82,6 +82,20 @@ fig = px.density_heatmap(df, x="total_bill", y="tip", facet_row="sex", facet_col
 fig.show()
 ```
 
+### 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", text_auto=True)
+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 +249,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,8 +5,8 @@ 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
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.8.11
   plotly:
     description: How to make Annotated Heatmaps in Python with Plotly.
     display_as: scientific
@@ -34,56 +34,55 @@ jupyter:
     thumbnail: thumbnail/ann_heat.jpg
 ---
 
-#### Simple Annotated Heatmap
+### Annotated Heatmaps with Plotly Express
+
+*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
 
-This page details the use of a [figure factory](/python/figure-factories/). For more examples with Heatmaps, see [this page](/python/heatmaps/).
+After creating a figure with `px.imshow`, you can add z-annotations with `.update_traces(texttemplate="%{z}")`.
 
 ```python
-import plotly.figure_factory as ff
+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 = ff.create_annotated_heatmap(z)
+fig = px.imshow(z, text_auto=True)
 fig.show()
 ```
 
-#### Defined Colorscale
+### Deprecated Figure Factory
 
-```python
-import plotly.figure_factory as ff
+The remaining examples show how to create Annotated Heatmaps with the deprecated `create_annotated_heatmap` [figure factory](/python/figure-factories/).
 
-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
+#### Simple Annotated Heatmap
 
 ```python
 import plotly.figure_factory as ff
 
-z = [[.1, .3, .5, .7],
-     [1.0, .8, .6, .4],
-     [.6, .4, .2, 0.0],
-     [.9, .7, .5, .3]]
+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]]
 
-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)
 fig.show()
 ```
 
 #### 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
 
@@ -102,6 +101,28 @@ fig = ff.create_annotated_heatmap(z, x=x, y=y, annotation_text=z_text, colorscal
 fig.show()
 ```
 
+Here is the same figure using `px.imshow()`
+
+```python
+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]]
+
+z_text = [['Win', 'Lose', 'Win'],
+          ['Lose', 'Lose', 'Win'],
+          ['Win', 'Win', 'Lose']]
+
+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()
+```
+
 #### Annotated Heatmap with numpy
 
 ```python
@@ -122,7 +143,20 @@ for i in range(len(fig.layout.annotations)):
 fig.show()
 ```
 
-#### Custom Hovertext
+Here is the same figure using `px.imshow()`
+
+```python
+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()
+```
+
+Here is a fairly contrived example showing how one can display a periodic table with custom text and hover using `ff.create_annotated_heatmap()` (scroll below to see the `px.imshow()` equivalent).
 
 ```python
 # Periodic Table Data
@@ -141,11 +175,11 @@ symbol = [['H', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '',
 
 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'],
+           ['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'],
+           ['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', '' ],
            ['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', ''],
@@ -165,7 +199,7 @@ atomic_mass = [[ 1.00794, .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.],
+color = [[.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.],
@@ -178,24 +212,20 @@ z = [[.8, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, 1.],
      [.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]]
 
+# 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)']]
+
 # Display element name and atomic mass on hover
 hover=[]
 for x in range(len(symbol)):
     hover.append([i + '<br>' + 'Atomic Mass: ' + str(j) if i else ''
                       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)']]
-
+import plotly.figure_factory as ff
 # Make Annotated Heatmap
-fig = ff.create_annotated_heatmap(z, annotation_text=symbol, text=hover,
+fig = ff.create_annotated_heatmap(color[::-1], annotation_text=symbol[::-1], text=hover[::-1],
                                  colorscale=colorscale, font_colors=['black'], hoverinfo='text')
 fig.update_layout(
      title_text='Periodic Table',
@@ -206,6 +236,25 @@ fig.update_layout(
 fig.show()
 ```
 
+Here is the same output using `px.imshow()` with much less array manipulation:
+
+```python
+import plotly.express as px
+import numpy as np
+
+fig = px.imshow(color, color_continuous_scale=colorscale, aspect="auto",
+               title='Periodic Table')
+fig.update_traces(
+    text=symbol, texttemplate="%{text}", textfont_size=12,
+    customdata=np.moveaxis([element, atomic_mass], 0,-1), 
+    hovertemplate="%{customdata[0]}<br>Atomic Mass: %{customdata[1]:.2f}<extra></extra>"
+)
+fig.update_xaxes(visible=False)
+fig.update_yaxes(visible=False)
+fig.update_coloraxes(showscale=False)
+fig.show()
+```
+
 #### Reference
 
 For more info on Plotly heatmaps, see: https://plotly.com/python/reference/heatmap/.<br> For more info on using colorscales with Plotly see: https://plotly.com/python/heatmap-and-contour-colorscales/ <br>For more info on `ff.create_annotated_heatmap()`, see the [full function reference](https://plotly.com/python-api-reference/generated/plotly.figure_factory.create_annotated_heatmap.html#plotly.figure_factory.create_annotated_heatmap)