Skip to content

Commit 9aaee25

Browse files
nicolaskruchtennicolaskruchten
authored
Merge pull request #3518 from plotly/text_auto
add text_auto to px
2 parents 12a1cf6 + d593b70 commit 9aaee25

16 files changed

+354
-122
lines changed

Diff for: ‎CHANGELOG.md

+5
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ This project adheres to [Semantic Versioning](http://semver.org/).
44

55
## UNRELEASED
66

7+
### Added
8+
9+
- `text_auto` argument to `px.bar`, `px.histogram`, `px.density_heatmap`, `px.imshow` [#3518](https://github.com/plotly/plotly.py/issues/3518)
10+
- Deprecated `ff.create_annotated_heatmap`, `ff.create_county_choropleth`, `ff.create_gantt` [#3518](https://github.com/plotly/plotly.py/issues/3518)
11+
712
### Updated
813
- 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:
914
- Horizontal color bars

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

+8-5
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ jupyter:
88
format_version: '1.3'
99
jupytext_version: 1.13.4
1010
kernelspec:
11-
display_name: Python 3 (ipykernel)
11+
display_name: Python 3
1212
language: python
1313
name: python3
1414
language_info:
@@ -20,7 +20,7 @@ jupyter:
2020
name: python
2121
nbconvert_exporter: python
2222
pygments_lexer: ipython3
23-
version: 3.7.11
23+
version: 3.8.11
2424
plotly:
2525
description: How to make 2D Histograms in Python with Plotly.
2626
display_as: statistical
@@ -82,14 +82,17 @@ fig = px.density_heatmap(df, x="total_bill", y="tip", facet_row="sex", facet_col
8282
fig.show()
8383
```
8484

85-
You can add the `z` values as text to 2D Histogram points using `fig.update_traces(texttemplate="%{z}")`
85+
### Displaying Text
86+
87+
*New in v5.5*
88+
89+
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.
8690

8791
```python
8892
import plotly.express as px
8993
df = px.data.tips()
9094

91-
fig = px.density_heatmap(df, x="total_bill", y="tip")
92-
fig.update_traces(texttemplate="%{z}")
95+
fig = px.density_heatmap(df, x="total_bill", y="tip", text_auto=True)
9396
fig.show()
9497
```
9598

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

+81-71
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ jupyter:
88
format_version: '1.3'
99
jupytext_version: 1.13.4
1010
kernelspec:
11-
display_name: Python 3 (ipykernel)
11+
display_name: Python 3
1212
language: python
1313
name: python3
1414
language_info:
@@ -20,7 +20,7 @@ jupyter:
2020
name: python
2121
nbconvert_exporter: python
2222
pygments_lexer: ipython3
23-
version: 3.7.11
23+
version: 3.8.11
2424
plotly:
2525
description: How to make Annotated Heatmaps in Python with Plotly.
2626
display_as: scientific
@@ -34,9 +34,11 @@ jupyter:
3434
thumbnail: thumbnail/ann_heat.jpg
3535
---
3636

37-
### Annotated Heatmaps with plotly.express and px.imshow
37+
### Annotated Heatmaps with Plotly Express
3838

39-
These examples use [px.imshow](/python/imshow) to create Annotated Heatmaps. px.imshow is the recommended way to create heatmaps with z-annotations.
39+
*New in v5.5*
40+
41+
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.
4042

4143

4244
#### Basic Annotated Heatmap for z-annotations
@@ -46,33 +48,19 @@ After creating a figure with `px.imshow`, you can add z-annotations with `.updat
4648
```python
4749
import plotly.express as px
4850

49-
df = px.data.medals_wide(indexed=True)
50-
51-
fig = px.imshow(df)
52-
fig.update_traces(texttemplate="%{z}")
53-
54-
fig.show()
55-
```
56-
57-
#### Custom Font
58-
59-
You can make changes to the font using `textfont`. Here we set the font size to 20.
60-
61-
```python
62-
import plotly.express as px
63-
64-
df = px.data.medals_wide(indexed=True)
65-
66-
fig = px.imshow(df)
67-
fig.update_traces(texttemplate="%{z}")
68-
fig.update_traces(textfont={"size":20})
51+
z = [[.1, .3, .5, .7, .9],
52+
[1, .8, .6, .4, .2],
53+
[.2, 0, .5, .7, .9],
54+
[.9, .8, .4, .2, 0],
55+
[.3, .4, .5, .7, 1]]
6956

57+
fig = px.imshow(z, text_auto=True)
7058
fig.show()
7159
```
7260

73-
### Annotated Heatmaps with [figure factory](/python/figure-factories/). For more examples with Heatmaps, see [this page](/python/heatmaps/).
61+
### Deprecated Figure Factory
7462

75-
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/).
63+
The remaining examples show how to create Annotated Heatmaps with the deprecated `create_annotated_heatmap` [figure factory](/python/figure-factories/).
7664

7765

7866
#### Simple Annotated Heatmap
@@ -90,54 +78,48 @@ fig = ff.create_annotated_heatmap(z)
9078
fig.show()
9179
```
9280

93-
#### Defined Colorscale
81+
#### Custom Text and X & Y Labels
82+
set `annotation_text` to a matrix with the same dimensions as `z`
83+
84+
> 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**
9485
9586
```python
9687
import plotly.figure_factory as ff
9788

98-
z = [[.1, .3, .5, .7],
99-
[1, .8, .6, .4],
100-
[.6, .4, .2, .0],
101-
[.9, .7, .5, .3]]
102-
103-
fig = ff.create_annotated_heatmap(z, colorscale='Viridis')
104-
fig.show()
105-
```
106-
107-
#### Custom Colorscale
89+
z = [[.1, .3, .5],
90+
[1.0, .8, .6],
91+
[.6, .4, .2]]
10892

109-
```python
110-
import plotly.figure_factory as ff
93+
x = ['Team A', 'Team B', 'Team C']
94+
y = ['Game Three', 'Game Two', 'Game One']
11195

112-
z = [[.1, .3, .5, .7],
113-
[1.0, .8, .6, .4],
114-
[.6, .4, .2, 0.0],
115-
[.9, .7, .5, .3]]
96+
z_text = [['Win', 'Lose', 'Win'],
97+
['Lose', 'Lose', 'Win'],
98+
['Win', 'Win', 'Lose']]
11699

117-
colorscale = [[0, 'navy'], [1, 'plum']]
118-
font_colors = ['white', 'black']
119-
fig = ff.create_annotated_heatmap(z, colorscale=colorscale, font_colors=font_colors)
100+
fig = ff.create_annotated_heatmap(z, x=x, y=y, annotation_text=z_text, colorscale='Viridis')
120101
fig.show()
121102
```
122103

123-
#### Custom Text and X & Y Labels
124-
set `annotation_text` to a matrix with the same dimensions as `z`
104+
Here is the same figure using `px.imshow()`
125105

126106
```python
127-
import plotly.figure_factory as ff
107+
import plotly.express as px
108+
109+
x = ['Team A', 'Team B', 'Team C']
110+
y = ['Game One', 'Game Two', 'Game Three']
128111

129112
z = [[.1, .3, .5],
130113
[1.0, .8, .6],
131114
[.6, .4, .2]]
132115

133-
x = ['Team A', 'Team B', 'Team C']
134-
y = ['Game Three', 'Game Two', 'Game One']
135-
136116
z_text = [['Win', 'Lose', 'Win'],
137117
['Lose', 'Lose', 'Win'],
138118
['Win', 'Win', 'Lose']]
139119

140-
fig = ff.create_annotated_heatmap(z, x=x, y=y, annotation_text=z_text, colorscale='Viridis')
120+
fig = px.imshow(z, x=x, y=y, color_continuous_scale='Viridis', aspect="auto")
121+
fig.update_traces(text=z_text, texttemplate="%{text}")
122+
fig.update_xaxes(side="top")
141123
fig.show()
142124
```
143125

@@ -161,7 +143,20 @@ for i in range(len(fig.layout.annotations)):
161143
fig.show()
162144
```
163145

164-
#### Custom Hovertext
146+
Here is the same figure using `px.imshow()`
147+
148+
```python
149+
import plotly.express as px
150+
import numpy as np
151+
np.random.seed(1)
152+
153+
z = np.random.randn(20, 20)
154+
155+
fig = px.imshow(z, text_auto=".2f", color_continuous_scale='Greys', aspect="auto")
156+
fig.show()
157+
```
158+
159+
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).
165160

166161
```python
167162
# Add Periodic Table Data
@@ -180,11 +175,11 @@ symbol = [['H', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '',
180175

181176
element = [['Hydrogen', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', 'Helium'],
182177
['Lithium', 'Beryllium', '', '', '', '', '', '', '', '', '', '', 'Boron', 'Carbon', 'Nitrogen', 'Oxygen', 'Fluorine', 'Neon'],
183-
['Sodium', 'Magnesium', '', '', '', '', '', '', '', '', '', '', 'Aluminium', 'Silicon', 'Phosphorus', 'Sulfur', 'Chlorine', ' Argon'],
184-
['Potassium', ' Calcium', ' Scandium', ' Titanium', ' Vanadium', ' Chromium', 'Manganese', 'Iron', 'Cobalt', 'Nickel', 'Copper', 'Zinc', 'Gallium', 'Germanium', 'Arsenic', 'Selenium', 'Bromine', 'Krypton'],
178+
['Sodium', 'Magnesium', '', '', '', '', '', '', '', '', '', '', 'Aluminium', 'Silicon', 'Phosphorus', 'Sulfur', 'Chlorine', 'Argon'],
179+
['Potassium', 'Calcium', 'Scandium', 'Titanium', 'Vanadium', 'Chromium', 'Manganese', 'Iron', 'Cobalt', 'Nickel', 'Copper', 'Zinc', 'Gallium', 'Germanium', 'Arsenic', 'Selenium', 'Bromine', 'Krypton'],
185180
['Rubidium', 'Strontium', 'Yttrium', 'Zirconium', 'Niobium', 'Molybdenum', 'Technetium', 'Ruthenium', 'Rhodium', 'Palladium', 'Silver', 'Cadmium', 'Indium', 'Tin', 'Antimony', 'Tellurium', 'Iodine', 'Xenon'],
186-
[' Cesium', ' Barium', '', 'Hafnium', 'Tantalum', 'Tungsten', 'Rhenium', 'Osmium', 'Iridium', 'Platinum', 'Gold', 'Mercury', 'Thallium', 'Lead', 'Bismuth', 'Polonium', 'Astatine', 'Radon'],
187-
[' Francium', ' Radium', '', 'Rutherfordium','Dubnium','Seaborgium','Bohrium','Hassium','Meitnerium','Darmstadtium','Roentgenium','Copernicium','Ununtrium','Ununquadium','Ununpentium','Ununhexium','Ununseptium','Ununoctium'],
181+
['Cesium', 'Barium', '', 'Hafnium', 'Tantalum', 'Tungsten', 'Rhenium', 'Osmium', 'Iridium', 'Platinum', 'Gold', 'Mercury', 'Thallium', 'Lead', 'Bismuth', 'Polonium', 'Astatine', 'Radon'],
182+
['Francium', 'Radium', '', 'Rutherfordium','Dubnium','Seaborgium','Bohrium','Hassium','Meitnerium','Darmstadtium','Roentgenium','Copernicium','Ununtrium','Ununquadium','Ununpentium','Ununhexium','Ununseptium','Ununoctium'],
188183
['', '', 'Lanthanum', 'Cerium', 'Praseodymium', 'Neodymium', 'Promethium', 'Samarium', 'Europium', 'Gadolinium', 'Terbium', 'Dysprosium', 'Holmium', 'Erbium', 'Thulium', 'Ytterbium', 'Lutetium', ''],
189184
['', '', 'Actinium', 'Thorium', 'Protactinium', 'Uranium', 'Neptunium', 'Plutonium', 'Americium', 'Curium', 'Berkelium', 'Californium', 'Einsteinium','Fermium' ,'Mendelevium', 'Nobelium', 'Lawrencium', '' ],
190185
['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', ''],
@@ -204,7 +199,7 @@ atomic_mass = [[ 1.00794, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0
204199
[.0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0],
205200
[.0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0]]
206201

207-
z = [[.8, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, 1.],
202+
color = [[.8, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, 1.],
208203
[.1, .2, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .7, .8, .8, .8, .9, 1.],
209204
[.1, .2, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .6, .7, .8, .8, .9, 1],
210205
[.1, .2, .3, .3, .3, .3, .3, .3, .3, .3, .3, .3, .6, .7, .8, .8, .9, 1.],
@@ -217,29 +212,44 @@ z = [[.8, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, .0, 1.],
217212
[.1, .1, .1, .3, .3, .3, .5, .5, .5, .7, .7, .7, .9, .9, .9, .0, .0, .0],
218213
[.2, .2, .2, .4, .4, .4, .6, .6, .6, .8, .8, .8, 1., 1., 1., .0, .0, .0]]
219214

220-
# Display element name and atomic mass on hover
221-
hover=[]
222-
for x in range(len(symbol)):
223-
hover.append([i + '<br>' + 'Atomic Mass: ' + str(j)
224-
for i, j in zip(element[x], atomic_mass[x])])
225-
226-
# Invert Matrices
227-
symbol = symbol[::-1]
228-
hover = hover[::-1]
229-
z = z[::-1]
230-
231215
# Set Colorscale
232216
colorscale=[[0.0, 'rgb(255,255,255)'], [.2, 'rgb(255, 255, 153)'],
233217
[.4, 'rgb(153, 255, 204)'], [.6, 'rgb(179, 217, 255)'],
234218
[.8, 'rgb(240, 179, 255)'],[1.0, 'rgb(255, 77, 148)']]
235219

220+
# Display element name and atomic mass on hover
221+
hover=[]
222+
for x in range(len(symbol)):
223+
hover.append([i + '<br>' + 'Atomic Mass: ' + str(j)
224+
for i, j in zip(element[x], atomic_mass[x])])
225+
226+
import plotly.figure_factory as ff
236227
# Make Annotated Heatmap
237-
fig = ff.create_annotated_heatmap(z, annotation_text=symbol, text=hover,
228+
fig = ff.create_annotated_heatmap(color[::-1], annotation_text=symbol[::-1], text=hover[::-1],
238229
colorscale=colorscale, font_colors=['black'], hoverinfo='text')
239230
fig.update_layout(title_text='Periodic Table')
240231
fig.show()
241232
```
242233

234+
Here is the same output using `px.imshow()` with much less array manipulation:
235+
236+
```python
237+
import plotly.express as px
238+
import numpy as np
239+
240+
fig = px.imshow(color, color_continuous_scale=colorscale, aspect="auto",
241+
title='Periodic Table')
242+
fig.update_traces(
243+
text=symbol, texttemplate="%{text}", textfont_size=12,
244+
customdata=np.moveaxis([element, atomic_mass], 0,-1),
245+
hovertemplate="%{customdata[0]}<br>Atomic Mass: %{customdata[1]:.2f}<extra></extra>"
246+
)
247+
fig.update_xaxes(visible=False)
248+
fig.update_yaxes(visible=False)
249+
fig.update_coloraxes(showscale=False)
250+
fig.show()
251+
```
252+
243253
#### Reference
244254

245255
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)

0 commit comments

Comments
 (0)