Creating and Updating Figures - Python - Plotly PDF

2020/2/6 Creating and Updating Figures | Python | Plotly
Creating and Updating Figures in

Python
Creating and Updating Figures from Python
Python
New to Plotly?
Representing Figures
Figures as dictionaries
The goal of plotly.py is to provide a pleasant Python interface for creating gure speci cations
for display in the Plotly.js JavaScript library. In Plotly.js, a gure is speci ed by a declarative
JSON data structure, and so the ultimate responsibility of plotly.py is to produce Python
dictionaries that can be serialized into a JSON data structure that represents a valid gure.
As a concrete example, here is a Python dictionary that represents a gure containing a single
bar trace and a title.
https://plot.ly/python/creating-and-updating-ﬁgures/ 1/43
fig = {
"data": [{"type": "bar",
"x": [1, 2, 3],
"y": [1, 3, 2]}],
"layout": {"title": {"text": "A Bar Chart"}}
}
# To display the figure defined by this dict, use the low-level plotly.i
o.show function
import plotly.io as pio
pio.show(fig)
A Bar Chart
2.5
1.5
The value of the top-level "data" key is a list of trace speci cations. Each trace speci cation
has a special "type" key that indicates the trace type that is being de ned (e.g. a "bar",
"scatter", "contour", etc.). The rest of the keys in the trace speci cation are used to
con gure the properties of the trace of this type.
The value of the top-level "layout" key is a dictionary that speci es the properties of the
gure's layout. In contrast to trace con guration options that apply to individual traces, the
layout con guration options apply to the gure as a whole, customizing items like the axes,
annotations, shapes, legend, and more.
The Full Reference page contains descriptions of all of the supported trace and layout options.
If working from the Full Reference to build gures as Python dictionaries and lists suites your
needs, go for it! This is a perfectly valid way to use plotly.py to build gures. On the other
hand, if you would like an API that o ers a bit more assistance, read on to learn about graph
objects.
Figures as graph objects

As an alternative to working with Python dictionaries, plotly.py provides a hierarchy of classes
called "graph objects" that may be used to construct gures. Graph objects have several
bene ts compared to plain dictionaries.
1. Graph objects provide precise data validation. So if you provide an invalid property
name or an invalid property value, an exception will be raised with a helpful error
message describing the problem.
2. Graph objects contain descriptions of each property as Python docstrings. You can use
these docstrings to learn about the available properties as an alternative to consulting
the Full Reference.
3. Properties of graph objects can be accessed using dictionary-style key lookup (e.g.
fig["layout"]) or class-style property access (e.g. fig.layout).
4. Graph objects support higher-level convenience functions for making updates to
already constructed gures, as described below.
Graph objects are stored in a hierarchy of modules under the plotly.graph_objects

package. Here is an example of one way that the gure above could be constructed using
graph objects.
import plotly.graph_objects as go
fig = go.Figure(
data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
layout=go.Layout(
title=go.layout.Title(text="A Bar Chart")
)
)
fig.show()
A Bar Chart
2.5
1.5
You can also create a graph object gure from a dictionary representation by passing the
dictionary to the gure constructor.
fig = go.Figure({
"data": [{"type": "bar",
"x": [1, 2, 3],
"y": [1, 3, 2]}],
"layout": {"title": {"text": "A Bar Chart"}}
})
fig.show()
A Bar Chart
2.5
1.5
Once you have a gure as a graph object, you can retrieve the dictionary representation using
the fig.to_dict() method. You can also retrieve the JSON string representation using the
fig.to_json() method.
Creating gures
This section summarizes several ways to create new graph object gures with plotly.py
Constructor
As demonstrated above, you can build a complete gure by passing trace and layout
speci cations to the plotly.graph_objects.Figure constructor. These trace and layout
speci cations can be either dictionaries or graph objects. Here, for example, the traces are
speci ed using graph objects and the layout is speci ed as a dictionary.
fig = go.Figure(
data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],
layout=dict(title=dict(text="A Bar Chart"))
)
fig.show()
A Bar Chart
2.5
1.5
Plotly express
Plotly express (included as the plotly.express module) is a high-level data exploration API
that produces graph object gures.
import plotly.express as px
df = px.data.iris()
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species")
# If you print fig, you'll see that it's just a regular figure with data
and layout
# print(fig)
fig.show()
7.5
6.5
sepal_length
5.5
Figure factories
Figure factories (included in plotly.py in the plotly.figure_factory module) are functions
that produce graph object gures, often to satisfy the needs of specialized domains. Here's an
example of using the create_quiver gure factory to construct a graph object gure that
displays a 2D quiver plot.
import numpy as np
import plotly.figure_factory as ff
x1,y1 = np.meshgrid(np.arange(0, 2, .2), np.arange(0, 2, .2))
u1 = np.cos(x1)*y1
v1 = np.sin(x1)*y1
fig = ff.create_quiver(x1, y1, u1, v1)

fig.show()
1.5
Make subplots
The plotly.subplots.make_subplots function produces a graph object gure that is
precon gured with a grid of subplots that traces can be added to. The add_trace function
will be discussed more below.
from plotly.subplots import make_subplots

fig = make_subplots(rows=1, cols=2)
fig.add_trace(go.Scatter(y=[4, 2, 1], mode="lines"), row=1, col=1)
fig.add_trace(go.Bar(y=[2, 1, 3]), row=1, col=2)
fig.show()
4 3
3.5 2.5
3 2
2.5
1.5
2
1
Updating gures
Regardless of how a graph object gure was constructed, it can be updated by adding
additional traces and modifying its properties.
Adding traces
New traces can be added to a graph object gure using the add_trace method. This method
accepts a graph object trace (an instance of go.Scatter, go.Bar, etc.) and adds it to the
gure. This allows you to start with an empty gure, and add traces to it sequentially.
fig = go.Figure()
fig.add_trace(go.Bar(x=[1, 2, 3], y=[1, 3, 2]))
fig.show()
2.5
1.5
You can also add traces to a gure produced by a gure factory or Plotly Express.
df = px.data.iris()
fig.add_trace(
go.Scatter(
x=[2, 4],
y=[4, 8],
mode="lines",
line=go.scatter.Line(color="gray"),
showlegend=False)
)
fig.show()
7.5
6.5
sepal_length
5.5
Adding traces to subplots

If a gure was created using plotly.subplots.make_subplots, then the row and col
argument to add_trace can be used to add a trace to a particular subplot.

fig.add_trace(go.Scatter(y=[4, 2, 1], mode="lines"), row=1, col=1)
fig.add_trace(go.Bar(y=[2, 1, 3]), row=1, col=2)
fig.show()
4 3
3.5 2.5
3 2
2.5
1.5
2
1
This also works for gures created by Plotly Express using the facet_row and or facet_col
arguments.
df = px.data.iris()
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species",
facet_col="species")
reference_line = go.Scatter(x=[2, 4],
y=[4, 8],
mode="lines",
line=go.scatter.Line(color="gray"),
showlegend=False)
fig.add_trace(reference_line, row=1, col=1)
fig.show()
species=setosa species=versicolor
7.5
6.5
sepal_length
5.5
Add trace convenience methods

As an alternative to the add_trace method, graph object gures have a family of methods of
the form add_{trace}, where {trace} is the name of a trace type, for constructing and
adding traces of each trace type. Here is the previous subplot example, adapted to add the
scatter trace using fig.add_scatter and to add the bar trace using fig.add_bar.

fig.add_scatter(y=[4, 2, 1], mode="lines", row=1, col=1)
fig.add_bar(y=[2, 1, 3], row=1, col=2)
fig.show()
4 3
3.5 2.5
3 2
2.5
1.5
2
1
Magic underscore notation

To make it easier to work with nested properties graph object constructors, and many graph
object methods, support magic underscore notation. This allows you to reference nested
properties by joining together multiple nested property names with underscores.
For example, specifying the gure title in the gure constructor without magic underscore
notation requires setting the layout argument to dict(title=dict(text="A Chart")).
Similarly, setting the line color of a scatter trace requires setting the marker property to
dict(color="crimson").
fig = go.Figure(
data=[go.Scatter(y=[1, 3, 2], line=dict(color="crimson"))],
layout=dict(title=dict(text="A Chart"))
)
fig.show()
A Chart
2.5
With magic underscore notation, you can accomplish the same thing by passing the gure
constructor a keyword argument named layout_title_text, and by passing the
go.Scatter constructor a keyword argument named line_color.
fig = go.Figure(
data=[go.Scatter(y=[1, 3, 2], line_color="crimson")],
layout_title_text="A Chart"
)
fig.show()
A Chart
2.5
Magic underscore notation is supported throughout the graph objects API, and it can often
signi cantly simplify operations involving deeply nested properties.
Note: When you see keyword arguments with underscores passed to a graph
object constructor or method, it is almost always safe to assume that it is an
application of magic underscore notation. We have to say "almost always" rather
than "always" because there are a few property names in the plotly schema that
contain underscores: error_x, error_y, error_z, copy_xstyle, copy_ystyle,
copy_zstyle, paper_bgcolor, and plot_bgcolor. These were added back in the early
days of the library (2012-2013) before we standardized on banning underscores
from property names.
The update layout method

Graph object gures support an update_layout method that may be used to update
multiple nested properties of a gure's layout. Here is an example of updating the text and
font size of a gure's title using update_layout.
fig = go.Figure(data=go.Bar(x=[1, 2, 3], y=[1, 3, 2]))
fig.update_layout(title_text="A Bar Chart",
title_font_size=30)
fig.show()
A Bar Chart
2.5
1.5
Note that the following update_layout operations are equivalent:

title_font_size=30)

title_font=dict(size=30))
fig.update_layout(title=dict(text="A Bar Chart"),

font=dict(size=30))
fig.update_layout({"title": {"text": "A Bar Chart",

"font": {"size": 30}}})
fig.update_layout(
title=go.layout.Title(text="A Bar Chart",
font=go.layout.title.Font(size=30)));
The update traces method

Graph object gures support an update_traces method that may be used to update
multiple nested properties of one or more of a gure's traces. To show some examples, we
will start with a gure that contains bar and scatter traces across two subplots.

fig.add_scatter(y=[4, 2, 3.5], mode="markers",

marker=dict(size=20, color="LightSeaGreen"),
name="a", row=1, col=1)
fig.add_bar(y=[2, 1, 3],
marker=dict(color="MediumPurple"),
name="b", row=1, col=1)
fig.add_scatter(y=[2, 3.5, 4], mode="markers",

marker=dict(size=20, color="MediumPurple"),
name="c", row=1, col=2)
marker=dict(color="LightSeaGreen"),
name="d", row=1, col=2)
fig.show()
4 4
3.5 3.5
3 3
2.5 2.5
2 2
1.5 1.5
Note that both scatter and bar traces have a marker.color property to control their
coloring. Here is an example of using update_traces to modify the color of all traces.



fig.update_traces(marker=dict(color="RoyalBlue"))
fig.show()
4 4
3.5 3.5
3 3
2.5 2.5
2 2
1.5 1.5
The update_traces method supports a selector argument to control which traces should
be updated. Only traces with properties that match the selector will be updated. Here is an
example of using a selector to only update the color of the bar traces



fig.update_traces(marker=dict(color="RoyalBlue"),
selector=dict(type="bar"))
fig.show()
4 4
3.5 3.5
3 3
2.5 2.5
2 2
1.5 1.5
Magic underscore notation can be used in the selector to match nested properties. Here is an
example of updating the color of all traces that were formally colored "MediumPurple".



fig.update_traces(marker_color="RoyalBlue",
selector=dict(marker_color="MediumPurple"))
fig.show()
4 4
3.5 3.5
3 3
2.5 2.5
2 2
1.5 1.5
For gures with subplots, the update_traces method also supports row and col arguments
to control which traces should be updated. Only traces in the speci ed subplot row and
column will be updated. Here is an example of updating the color of all traces in the second
subplot column



fig.update_traces(marker=dict(color="RoyalBlue"),
col=2)
fig.show()
4 4
3.5 3.5
3 3
2.5 2.5
2 2
1.5 1.5
The update_traces method can also be used on gures produced by gure factories or
Plotly Express. Here's an example of updating the regression lines produced by Plotly Express
to be dotted.
import pandas as pd
df = px.data.iris()
facet_col="species", trendline="ols")
fig.update_traces(
line=dict(dash="dot", width=4),
selector=dict(type="scatter", mode="lines"))
fig.show()
8
7.5
6.5
sepal_length
5.5
Overwrite existing properties when

using update methods
update_layout and update_traces have an overwrite keyword argument, defaulting to
False, in which case updates are applied recursively to the existing nested property structure.
When set to True, the prior value of existing properties is overwritten with the provided value.
In the example below, the red color of markers is overwritten when updating marker in
update_traces with overwrite=True. Note that setting instead marker_opacity with the
magic underscore would not overwrite marker_color because properties would be
overwritten starting only at the level of marker.opacity.
fig = go.Figure(go.Bar(x=[1, 2, 3], y=[6, 4, 9],
marker_color="red")) # will be overwritten below
fig.update_traces(
overwrite=True,
marker={"opacity": 0.4}
)
fig.show()
The for each trace method

Suppose the updates that you want to make to a collection of traces depend on the current
values of certain trace properties. The update_traces method cannot handle this situation,
but the for_each_trace method can.
As its rst argument, the for_each_trace method accepts a function that accepts and
updates one trace at a time. Like update_traces, for_each_trace also accepts selector,
row, and col arguments to control which traces should be considered.
Here is an example of using for_each_trace to replace the equal-sign with a colon in the
legend name of each trace in a gure produced by Plotly Express.
import pandas as pd
df = px.data.iris()
fig.for_each_trace(
lambda trace: trace.update(name=trace.name.replace("=", ": ")),
)
fig.show()
7.5
6.5
sepal_length
5.5
The update axis methods

Graph object gures support update_xaxes and update_yaxes methods that may be used
to update multiple nested properties of one or more of a gure's axes. Here is an example of
using update_xaxes to disable the vertical grid lines across all subplots in a gure produced
by Plotly Express.
import pandas as pd
df = px.data.iris()
facet_col="species")
fig.update_xaxes(showgrid=False)
fig.show()
8
7.5
6.5
sepal_length
5.5
There are also for_each_xaxis and for_each_yaxis methods that are analogous to the
for_each_trace method described above. For non-cartesian subplot types (e.g. polar), there
are additional update_{type} and for_each_{type} methods (e.g. update_polar,
for_each_polar).
Other update methods

go gures also support update_layout_images in order to update background layout
images, update_annotations in order to update annotations, and update-shapes in order
to update shapes.
Chaining gure operations

All of the gure update operations described above are methods that return a reference to
the gure being modi ed. This makes it possible the chain multiple gure modi cation
operations together into a single expression.
Here is an example of a chained expression that creates a faceted scatter plot with OLS trend
lines using Plotly Express, sets the title font size using update_layout, disables vertical grid
lines using update_xaxes, updates the width and dash pattern of the trend lines using
update_traces, and then displays the gure using show.
df = px.data.iris()
(px.scatter(df, x="sepal_width", y="sepal_length", color="species",
facet_col="species", trendline="ols", title="Iris Dataset")
.update_layout(title_font_size=24)
.update_xaxes(showgrid=False)
.update_traces(
line=dict(dash="dot", width=4),
selector=dict(type="scatter", mode="lines"))
).show()
Iris Dataset
8
7.5
6.5
sepal_length
5.5
Property assignment
Trace and layout properties can be updated using property assignment syntax. Here is an
example of setting the gure title using property assignment
example of setting the gure title using property assignment.
fig.layout.title.text = "A Bar Chart"
fig.show()
A Bar Chart
2.5
1.5
And here is an example of updating the bar outline using property assignment
fig.data[0].marker.line.width = 4
fig.data[0].marker.line.color = "black"
fig.show()
2.5
1.5
Products Pricing About Us
Dash Enterprise Pricing Careers

Chart Studio Resources
Plotly OEM Blog
Support JOIN OUR MAILING LIST
Community Support Sign up to stay in the loop with all
Documentation things Plotly — from Dash Club to

product updates, webinars, and
more!
Subscribe
Copyright © 2020 Plotly. All rights reserved. Terms of Service Privacy Policy

Creating and Updating Figures - Python - Plotly PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Creating and Updating Figures - Python - Plotly PDF

Uploaded by

Copyright:

Available Formats

2020/2/6 Creating and Updating Figures | Python | Plotly

Creating and Updating Figures in

Figures as graph objects

Graph objects are stored in a hierarchy of modules under the plotly.graph_objects

fig = ff.create_quiver(x1, y1, u1, v1)

from plotly.subplots import make_subplots

Adding traces to subplots

from plotly.subplots import make_subplots

Add trace convenience methods

from plotly.subplots import make_subplots

Magic underscore notation

The update layout method

Note that the following update_layout operations are equivalent:

fig.update_layout(title_text="A Bar Chart",

fig.update_layout(title_text="A Bar Chart",

fig.update_layout(title=dict(text="A Bar Chart"),

fig.update_layout({"title": {"text": "A Bar Chart",

The update traces method

from plotly.subplots import make_subplots

fig.add_scatter(y=[4, 2, 3.5], mode="markers",

fig.add_scatter(y=[2, 3.5, 4], mode="markers",

from plotly.subplots import make_subplots

fig.add_scatter(y=[4, 2, 3.5], mode="markers",

fig.add_scatter(y=[2, 3.5, 4], mode="markers",

from plotly.subplots import make_subplots

fig.add_scatter(y=[4, 2, 3.5], mode="markers",

fig.add_scatter(y=[2, 3.5, 4], mode="markers",

from plotly.subplots import make_subplots

fig.add_scatter(y=[4, 2, 3.5], mode="markers",

fig.add_scatter(y=[2, 3.5, 4], mode="markers",

from plotly.subplots import make_subplots

fig.add_scatter(y=[4, 2, 3.5], mode="markers",

fig.add_scatter(y=[2, 3.5, 4], mode="markers",

Overwrite existing properties when

The for each trace method

The update axis methods

Other update methods

Chaining gure operations

Products Pricing About Us

Dash Enterprise Pricing Careers

Support JOIN OUR MAILING LIST

Community Support Sign up to stay in the loop with all

Documentation things Plotly — from Dash Club to

You might also like