Location of reference for all magics to use in update_layout

Hi.

I am using Plotly express and would like to use update_layout() method to use more advanced features with it. The Creating and Updating Layout guide has this example:

fig = go.Figure(
data=[go.Scatter(y=[1, 3, 2], line_color=“crimson”)],
layout_title_text=“Another Graph Object Figure With Magic Underscore Notation”
)

Where can I find a master list of all your magic underscore attributes? I checked Python Figure Reference but layout_title_text is not listed there. Also, what is the difference between magic underscore attributes like layout_title_text and the sorts of attributes listed in this reference page?

—Edit—
Looking again in the Reference page I see this…

Do I correctly interpret this as meaning that I can take any attribute from the page and use it as an argument in update_layour() in the form parent_child_baby?

Thank you.
Ilya

Hi @joemac1985,

What you call magics is in fact a shorter method to access an inner item of a nested dictionary.

Using low level coding, suppose that we have the following initial settings for the dict xaxis:

layout = go.Layout(xaxis= {'range': [0, 12],
                           'showticklabels': False,
                           'title': {'text':  'x',
                                     'font': {'family': 'Balto',
                                              'size':10
                                             }
                                    } 
                          }
                   )

A nested dict is like a rooted tree: Here xaxis is the root. Magics is a Plotly rule of giving the path from the root to a children, located at some tree level.

We are updating the font size as follows:

xaxis_title_font_size=12

instead of the classical rule:

xaxis['title']['font']['size']=12    

Hence no reference to these magics is needed because from https://plotly.com/python/reference we can find the path from a root to a children and then just add underscore between the root and the next successor and two successive children.

Thank you. This is what I was thinking.

But in practice, how do you use the Reference Page to discover that such a chain of items in a nested dictionary is possible? In your example, how would you know that xaxis is a root?

In the Reference Page, size is under font, font is under text, text is under title, which is listed in the Layout section. However, xaxis is not listed as the root of title but is listed in the separate section Axis and Subplots within the Layout section. So how would you have known the xaxis is the root?

In other words, how do you read the Reference Page to construct such trees?

The root is always the figure, which has two main keys: layout (of which xaxis is a child) and data (a list of traces) and this is generally how the “parent” is listed in the reference page, for example size has parent layout.xaxis.title.font therefore its full path is <figure>.layout.xaxis.title.font.size.

Given this, you may use fig.update_layout(xaxis_title_font_size=12) or fig.layout.xaxis.title.font.size=12 as you like.

I should add that specifically in the case of xaxis there is a special shortcut update method that you can use like this: fig.update_xaxes(title_font_size=12) which updates all the x axes in a figure. There are a few other updaters like update_traces() that are documented in https://plotly.com/python/creating-and-updating-figures/

@joemac1985,

When you adopt Plotly as the graphing library , you first learn the definition of go.Figure, and write code to define different traces with various layouts, i.e you are making experiments with classes in
plotly.graph_objects.

Suppose that you generated a Figure, but you’d like to have smaller font size for xaxis title. In this case you don’t search the python/reference and read the first met title, because there is a layout title (the plot tittle) the xaxis title, yaxis title (and for 3d plots zaxis title). But since you want to change the title font for xaxis your (necessary) bakground in graph_objects suggests to search first on python/reference , xaxis, because one of its attrinutes must be changed. Scrolling through the list of xaxis attributes you will stumble upon title. After title are listed its attributes, and you find the font and then the font size, Hence you’ll make the update:

fig.update_layout(xaxis_title_font_size=12)

In this case the root was xaxis.

Second searching method:

display `help(go.layout.XAxis)’

Here the xaxis properties are listed in alphabetical order.

The title is listed as follows:

title
 |          :class:`plotly.graph_objects.layout.xaxis.Title`
 |          instance or dict with compatible properties

Now display (print)

help(go.layout.xaxis.Title)

and you’ll find out font as a property

Display:

help(go.layout.xaxis.title.Font

and you can see the size.

Hence depending on how well you first studied and experimented with plotly.graph_objects, you are able to find what should be updated and how to set the root of search and the path to a convenient property.

In the reference, there are…
(1) In Trace Type section, many xaxis with parent as some data type (scatter, bar, etc.)
(2) In Axes and Subplots, an xaxis with parent of layout.

Say I have a figure with a scatterplot and I wish to change the xaxis in some manner, how would I decide if I should choose xaxis from trace type or layout?

Good question! The xaxis key in any given trace is actually a “pointer” to an xaxis key in layout (as there can be more than one of the latter).

So if you have layout.xaxis and layout.xaxis2 then you might have a trace where <trace>.xaxis="x" and another where <trace>.xaxis="x2" but you can’t set the x axis title from within a trace.

For historical reasons, while this pattern also applies to <trace>.coloraxis and layout.coloraxis, traces also have an “on board” colorscale and colorbar, so for continuous color, you can in fact set the colorbar title from within the trace, but this is considered “legacy” at this point.

Hope this helps!

Thank you the help. I think I understand.

@joemac1985 I’ve pulled together a new top-level page that is intended to explain everything about the structure of figures and how the various bits relate to each other, and how to read the Figure Reference (including a new preamble in the figure reference itself explaining how to read it)

Check it out here: https://plotly.com/python/figure-structure/ and please feel free to give feedback if things are missing or unclear :slight_smile:

1 Like

This is magnifique! It is exactly what I am looking for. I will go through it and add comments here, in case they are useful to you.