Ctrl+K

Plotly Mechanics

Plotly Mechanics#

Plotly.js, the JavaScript library plotly is based on understands figures as trees with named nodes called attributes. The root node of the tree has three top-level attributes.

  • The top-level data attribute consists of a list of dicts referred to as traces.

    • Each trace has a plot type (scatter, bar, pie, etc.), and is drawn on a single subplot. Traces can have a single legend, and other attributes depending on trace type.

  • The top-level layout attribute is referred to as “the layout” and consists of a dict with attributes that control non-data parts of the figure. Parts of the figure governed by the layout attribute include:

    • Dimensions and margins

    • Templates, fonts, colors, hover labels

    • Titles and legends

    • Non-data marks such as annotations, shapes, and images

    • Controls like buttons, toggles, menus, or sliders

  • The top-level frames attribute does not exist for all types of plots. frames consists of a list of dicts that define sequential frames in an animated plot. Each frame in the sequence has its own data attribute (and other parameters).

When building a figure, you do not have to populate every attribute of every object. The JavaScript layer can compute default values for some unspecified attributes.

Let’s look at an example for a simple line plot, using plotly:

import plotly.express as px # import statement
fig = px.line(x=["a","b","c"], y=[1,3,2], title="sample figure") # figure with sample data
fig # show figure

print(fig) # show back-end data for this figure

Figure({
    'data': [{'hovertemplate': 'x=%{x}<br>y=%{y}<extra></extra>',
              'legendgroup': '',
              'line': {'color': '#636efa', 'dash': 'solid'},
              'marker': {'symbol': 'circle'},
              'mode': 'lines',
              'name': '',
              'orientation': 'v',
              'showlegend': False,
              'type': 'scatter',
              'x': array(['a', 'b', 'c'], dtype=object),
              'xaxis': 'x',
              'y': array([1, 3, 2]),
              'yaxis': 'y'}],
    'layout': {'legend': {'tracegroupgap': 0},
               'template': '...',
               'title': {'text': 'sample figure'},
               'xaxis': {'anchor': 'y', 'domain': [0.0, 1.0], 'title': {'text': 'x'}},
               'yaxis': {'anchor': 'x', 'domain': [0.0, 1.0], 'title': {'text': 'y'}}}
})

The JSON object generated as part of plotly’s back-end process:

Figure({
    'data': [{'hovertemplate': 'x=%{x}<br>y=%{y}<extra></extra>',
              'legendgroup': '',
              'line': {'color': '#636efa', 'dash': 'solid'},
              'mode': 'lines',
              'name': '',
              'orientation': 'v',
              'showlegend': False,
              'type': 'scatter',
              'x': array(['a', 'b', 'c'], dtype=object),
              'xaxis': 'x',
              'y': array([1, 3, 2]),
              'yaxis': 'y'}],
    'layout': {'legend': {'tracegroupgap': 0},
               'template': '...',
               'title': {'text': 'sample figure'},
               'xaxis': {'anchor': 'y', 'domain': [0.0, 1.0], 'title': {'text': 'x'}},
               'yaxis': {'anchor': 'x', 'domain': [0.0, 1.0], 'title': {'text': 'y'}}}
})

We can use fig.to_dict() and fig.to_json() to represent the back-end of a plotly figure as a dictionary or JSON object, respectively.

A few notes on this figure structure:

  • 2D Cartesian coordinate system subplots are the most commonly-used type of subplot. In plotly, traces compatible with these subplots support xaxis and yaxis attributes. Trace types compatible with 2D cartesian subplots include scatterplots, bar charts, histograms, and box plots.

  • Both X and Y axes support a type attribute. The type attribute can modify a trace to show continuous values, temporal values, or categorical values.

Additional Resources#

Contents