Skip to content

Remove deprecated Figure Factory functions #5627

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emilykl merged 9 commits into from
Jun 22, 2026
Merged

Remove deprecated Figure Factory functions #5627

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d32d856
remove deprecated Figure Factory functions
emilykl Jun 18, 2026
b45f9d9
remove tests for removed Figure Factory functions
emilykl Jun 18, 2026
4c0dad7
add changelog entry
emilykl Jun 18, 2026
901ebed
formatting
emilykl Jun 18, 2026
3185b9a
update docs to reflect removed figure factory functions
emilykl Jun 18, 2026
a203a2b
remove plotly-geo, pyshp, and shapely dev dependencies (used by remov…
emilykl Jun 19, 2026
6bfa2d4
update metadata
emilykl Jun 19, 2026
bdfe6fd
docs edits
emilykl Jun 19, 2026
c8ea5ff
Update CHANGELOG.md
emilykl Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).

## Unreleased

### Removed
- Remove the deprecated Figure Factory functions `create_2d_density`, `create_annotated_heatmap`, `create_bullet`, `create_candlestick`, `create_choropleth`, `create_distplot`, `create_facet_grid`, `create_gantt`, `create_hexbin_mapbox`, `create_ohlc`, `create_scatterplotmatrix`, and `create_violin`. [[#5627](https://github.com/plotly/plotly.py/pull/5627)]
Comment thread
emilykl marked this conversation as resolved.
Outdated

### Fixed
- Raise a clear `ValueError` when an unsupported marginal plot type is passed to Plotly Express, instead of failing later with a cryptic `'NoneType' object has no attribute 'constructor'` message [[#5625](https://github.com/plotly/plotly.py/pull/5625)], with thanks to @eugen-goebel for the contribution!

Expand Down
18 changes: 0 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,24 +125,6 @@ or conda
conda install -c conda-forge python-kaleido
```

### Extended Geo Support

Some plotly.py features rely on fairly large geographic shape files. The county
choropleth figure factory is one such example. These shape files are distributed as a
separate `plotly-geo` package. This package can be installed using pip...

```
pip install plotly-geo==1.0.0
```

or conda

```
conda install -c plotly plotly-geo=1.0.0
```

`plotly-geo` can be found on Github at https://github.com/plotly/plotly-geo.

## Copyright and Licenses

Code and documentation copyright 2019 Plotly, Inc.
Expand Down
11 changes: 0 additions & 11 deletions doc/apidoc/plotly.figure_factory.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,11 @@
:toctree: generated/
:template: function.rst

create_2d_density
create_annotated_heatmap
create_bullet
create_candlestick
create_choropleth
create_dendrogram
create_distplot
create_facet_grid
create_gantt
create_hexbin_map
create_ohlc
create_quiver
create_scatterplotmatrix
create_streamline
create_table
create_ternary_contour
create_trisurf
create_violin

107 changes: 13 additions & 94 deletions doc/python/annotated-heatmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,14 @@ jupyter:

*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.
Plotly Express provides the [`px.imshow()`](/python/heatmaps/) function which can be used for creating annotated heatmaps.


#### Basic Annotated Heatmap for z-annotations

*New in v5.5*

After creating a figure with `px.imshow`, you can add z-annotations with `.update_traces(texttemplate="%{z}")`.
When creating a figure with `px.imshow`, you can pass the parameter `text_auto=True` to add z-annotations.

```python
import plotly.express as px
Expand All @@ -60,50 +60,9 @@ fig = px.imshow(z, text_auto=True)
fig.show()
```

### Deprecated Figure Factory
#### Custom Text and Axis Labels

The remaining examples show how to create Annotated Heatmaps with the deprecated `create_annotated_heatmap` [figure factory](/python/figure-factories/).


#### Simple Annotated Heatmap

```python
import plotly.figure_factory as ff

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.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

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.show()
```

Here is the same figure using `px.imshow()`
To annotate cells with text other than the `z` values, set the `text` attribute with `update_traces` and display it with a `texttemplate`. You can also label the axes by passing `x` and `y`.

```python
import plotly.express as px
Expand All @@ -125,27 +84,9 @@ fig.update_xaxes(side="top")
fig.show()
```

#### Annotated Heatmap with numpy

```python
import plotly.figure_factory as ff
import numpy as np
np.random.seed(1)

z = np.random.randn(20, 20)
z_text = np.around(z, decimals=2) # Only show rounded value (full value on hover)

fig = ff.create_annotated_heatmap(z, annotation_text=z_text, colorscale='Greys',
hoverinfo='z')

# Make text size smaller
for i in range(len(fig.layout.annotations)):
fig.layout.annotations[i].font.size = 8

fig.show()
```
#### Annotated Heatmap with a NumPy Array

Here is the same figure using `px.imshow()`
`px.imshow` works directly with NumPy arrays. Pass a [`d3-format`](https://github.com/d3/d3-format/tree/v1.4.5#d3-format) string to `text_auto` to control how the annotations are formatted.

```python
import plotly.express as px
Expand All @@ -158,10 +99,14 @@ 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).
#### Periodic Table with Custom Text and Hover

`px.imshow()` can produce more elaborate annotated heatmaps. The example below renders a periodic table: the cell labels come from a custom `text` array, while `customdata` combined with a `hovertemplate` displays the element name and atomic mass on hover.

```python
# Periodic Table Data
import plotly.express as px
import numpy as np

symbol = [['H', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', 'He'],
['Li', 'Be', '', '', '', '', '', '', '', '', '', '', 'B', 'C', 'N', 'O', 'F', 'Ne'],
['Na', 'Mg', '', '', '', '', '', '', '', '', '', '', 'Al', 'Si', 'P', 'S', 'Cl', 'Ar'],
Expand Down Expand Up @@ -214,36 +159,10 @@ color = [[.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])])

import plotly.figure_factory as ff
# Make Annotated Heatmap
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',
margin=dict(l=10, r=10, t=10, b=10, pad=10),
xaxis=dict(zeroline=False, showgrid=False),
yaxis=dict(zeroline=False, showgrid=False, scaleanchor="x"),
)
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(
Expand All @@ -259,4 +178,4 @@ 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)
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/
37 changes: 0 additions & 37 deletions doc/python/choropleth-maps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,43 +349,6 @@ fig.update_layout(
fig.show()
```

#### County Choropleth Figure Factory

Plotly also includes a [legacy "figure factory" for creating US county-level choropleth maps](/python/county-choropleth/).

```python
import plotly.figure_factory as ff

import numpy as np
import pandas as pd

df_sample = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/laucnty16.csv')
df_sample['State FIPS Code'] = df_sample['State FIPS Code'].apply(lambda x: str(x).zfill(2))
df_sample['County FIPS Code'] = df_sample['County FIPS Code'].apply(lambda x: str(x).zfill(3))
df_sample['FIPS'] = df_sample['State FIPS Code'] + df_sample['County FIPS Code']

colorscale = ["#f7fbff", "#ebf3fb", "#deebf7", "#d2e3f3", "#c6dbef", "#b3d2e9", "#9ecae1",
"#85bcdb", "#6baed6", "#57a0ce", "#4292c6", "#3082be", "#2171b5", "#1361a9",
"#08519c", "#0b4083", "#08306b"
]
endpts = list(np.linspace(1, 12, len(colorscale) - 1))
fips = df_sample['FIPS'].tolist()
values = df_sample['Unemployment Rate (%)'].tolist()


fig = ff.create_choropleth(
fips=fips, values=values, scope=['usa'],
binning_endpoints=endpts, colorscale=colorscale,
show_state_data=False,
show_hover=True,
asp = 2.9,
title_text = 'USA by Unemployment %',
legend_title = '% unemployed'
)
fig.layout.template = None
fig.show()
```

#### Reference

See [function reference for `px.(choropleth)`](https://plotly.com/python-api-reference/generated/plotly.express.choropleth) or https://plotly.com/python/reference/choropleth/ for more information and chart attribute options!
Loading