plotly.graph_objects.Figure

class plotly.graph_objects.Figure(data=None, layout=None, frames=None, skip_invalid=False, **kwargs)
__init__(data=None, layout=None, frames=None, skip_invalid=False, **kwargs)

Create a new :class:Figure instance

Parameters

  • data –

    The ‘data’ property is a tuple of trace instances that may be specified as:

    • A list or tuple of trace instances (e.g. [Scatter(…), Bar(…)])

    • A single trace instance (e.g. Scatter(…), Bar(…), etc.)

    • A list or tuple of dicts of string/value properties where: - The ‘type’ property specifies the trace type

      One of: [‘bar’, ‘barpolar’, ‘box’, ‘candlestick’,

      ’carpet’, ‘choropleth’, ‘choroplethmap’, ‘choroplethmapbox’, ‘cone’, ‘contour’, ‘contourcarpet’, ‘densitymap’, ‘densitymapbox’, ‘funnel’, ‘funnelarea’, ‘heatmap’, ‘histogram’, ‘histogram2d’, ‘histogram2dcontour’, ‘icicle’, ‘image’, ‘indicator’, ‘isosurface’, ‘mesh3d’, ‘ohlc’, ‘parcats’, ‘parcoords’, ‘pie’, ‘sankey’, ‘scatter’, ‘scatter3d’, ‘scattercarpet’, ‘scattergeo’, ‘scattergl’, ‘scattermap’, ‘scattermapbox’, ‘scatterpolar’, ‘scatterpolargl’, ‘scattersmith’, ‘scatterternary’, ‘splom’, ‘streamtube’, ‘sunburst’, ‘surface’, ‘table’, ‘treemap’, ‘violin’, ‘volume’, ‘waterfall’]

      • All remaining properties are passed to the constructor of the specified trace type

      (e.g. [{‘type’: ‘scatter’, …}, {‘type’: ‘bar, …}])

  • layout –

    The ‘layout’ property is an instance of Layout that may be specified as:

  • frames –

    The ‘frames’ property is a tuple of instances of Frame that may be specified as:

    • A list or tuple of instances of plotly.graph_objects.Frame

    • A list or tuple of dicts of string/value properties that will be passed to the Frame constructor

  • skip_invalid (bool) – If True, invalid properties in the figure specification will be skipped silently. If False (default) invalid properties in the figure specification will result in a ValueError

Raises

ValueError – if a property in the specification of data, layout, or frames is invalid AND skip_invalid is False

Methods

__init__([data, layout, frames, skip_invalid])

Create a new :class:Figure instance

add_annotation([arg, align, arrowcolor, …])

Create and add a new annotation to the figure’s layout

add_bar([alignmentgroup, base, basesrc, …])

Add a new Bar trace

add_barpolar([base, basesrc, customdata, …])

Add a new Barpolar trace

add_box([alignmentgroup, boxmean, …])

Add a new Box trace

add_candlestick([close, closesrc, …])

Add a new Candlestick trace

add_carpet([a, a0, aaxis, asrc, b, b0, …])

Add a new Carpet trace

add_choropleth([autocolorscale, coloraxis, …])

Add a new Choropleth trace

add_choroplethmap([autocolorscale, below, …])

Add a new Choroplethmap trace

add_choroplethmapbox([autocolorscale, …])

Add a new Choroplethmapbox trace

add_cone([anchor, autocolorscale, cauto, …])

Add a new Cone trace

add_contour([autocolorscale, autocontour, …])

Add a new Contour trace

add_contourcarpet([a, a0, asrc, atype, …])

Add a new Contourcarpet trace

add_densitymap([autocolorscale, below, …])

Add a new Densitymap trace

add_densitymapbox([autocolorscale, below, …])

Add a new Densitymapbox trace

add_funnel([alignmentgroup, cliponaxis, …])

Add a new Funnel trace

add_funnelarea([aspectratio, baseratio, …])

Add a new Funnelarea trace

add_heatmap([autocolorscale, coloraxis, …])

Add a new Heatmap trace

add_histogram([alignmentgroup, autobinx, …])

Add a new Histogram trace

add_histogram2d([autobinx, autobiny, …])

Add a new Histogram2d trace

add_histogram2dcontour([autobinx, autobiny, …])

Add a new Histogram2dContour trace

add_hline(y[, row, col, …])

Add a horizontal line to a plot or subplot that extends infinitely in the x-dimension.

add_hrect(y0, y1[, row, col, …])

Add a rectangle to a plot or subplot that extends infinitely in the x-dimension.

add_icicle([branchvalues, count, …])

Add a new Icicle trace

add_image([colormodel, customdata, …])

Add a new Image trace

add_indicator([align, customdata, …])

Add a new Indicator trace

add_isosurface([autocolorscale, caps, …])

Add a new Isosurface trace

add_layout_image([arg, layer, name, …])

Create and add a new image to the figure’s layout

add_mesh3d([alphahull, autocolorscale, …])

Add a new Mesh3d trace

add_ohlc([close, closesrc, customdata, …])

Add a new Ohlc trace

add_parcats([arrangement, bundlecolors, …])

Add a new Parcats trace

add_parcoords([customdata, customdatasrc, …])

Add a new Parcoords trace

add_pie([automargin, customdata, …])

Add a new Pie trace

add_sankey([arrangement, customdata, …])

Add a new Sankey trace

add_scatter([alignmentgroup, cliponaxis, …])

Add a new Scatter trace

add_scatter3d([connectgaps, customdata, …])

Add a new Scatter3d trace

add_scattercarpet([a, asrc, b, bsrc, …])

Add a new Scattercarpet trace

add_scattergeo([connectgaps, customdata, …])

Add a new Scattergeo trace

add_scattergl([connectgaps, customdata, …])

Add a new Scattergl trace

add_scattermap([below, cluster, …])

Add a new Scattermap trace

add_scattermapbox([below, cluster, …])

Add a new Scattermapbox trace

add_scatterpolar([cliponaxis, connectgaps, …])

Add a new Scatterpolar trace

add_scatterpolargl([connectgaps, …])

Add a new Scatterpolargl trace

add_scattersmith([cliponaxis, connectgaps, …])

Add a new Scattersmith trace

add_scatterternary([a, asrc, b, bsrc, c, …])

Add a new Scatterternary trace

add_selection([arg, line, name, opacity, …])

Create and add a new selection to the figure’s layout

add_shape([arg, editable, fillcolor, …])

Create and add a new shape to the figure’s layout

add_splom([customdata, customdatasrc, …])

Add a new Splom trace

add_streamtube([autocolorscale, cauto, …])

Add a new Streamtube trace

add_sunburst([branchvalues, count, …])

Add a new Sunburst trace

add_surface([autocolorscale, cauto, cmax, …])

Add a new Surface trace

add_table([cells, columnorder, …])

Add a new Table trace

add_trace(trace[, row, col, secondary_y, …])

Add a trace to the figure

add_traces(data[, rows, cols, secondary_ys, …])

Add traces to the figure

add_treemap([branchvalues, count, …])

Add a new Treemap trace

add_violin([alignmentgroup, bandwidth, box, …])

Add a new Violin trace

add_vline(x[, row, col, …])

Add a vertical line to a plot or subplot that extends infinitely in the y-dimension.

add_volume([autocolorscale, caps, cauto, …])

Add a new Volume trace

add_vrect(x0, x1[, row, col, …])

Add a rectangle to a plot or subplot that extends infinitely in the y-dimension.

add_waterfall([alignmentgroup, base, …])

Add a new Waterfall trace

append_trace(trace, row, col)

Add a trace to the figure bound to axes at the specified row, col index.

batch_animate([duration, easing])

Context manager to animate trace / layout updates

batch_update()

A context manager that batches up trace and layout assignment operations into a singe plotly_update message that is executed when the context exits.

for_each_annotation(fn[, selector, row, …])

Apply a function to all annotations that satisfy the specified selection criteria

for_each_coloraxis(fn[, selector, row, col])

Apply a function to all coloraxis objects that satisfy the specified selection criteria

for_each_geo(fn[, selector, row, col])

Apply a function to all geo objects that satisfy the specified selection criteria

for_each_layout_image(fn[, selector, row, …])

Apply a function to all images that satisfy the specified selection criteria

for_each_legend(fn[, selector, row, col])

Apply a function to all legend objects that satisfy the specified selection criteria

for_each_map(fn[, selector, row, col])

Apply a function to all map objects that satisfy the specified selection criteria

for_each_mapbox(fn[, selector, row, col])

Apply a function to all mapbox objects that satisfy the specified selection criteria

for_each_polar(fn[, selector, row, col])

Apply a function to all polar objects that satisfy the specified selection criteria

for_each_scene(fn[, selector, row, col])

Apply a function to all scene objects that satisfy the specified selection criteria

for_each_selection(fn[, selector, row, col, …])

Apply a function to all selections that satisfy the specified selection criteria

for_each_shape(fn[, selector, row, col, …])

Apply a function to all shapes that satisfy the specified selection criteria

for_each_smith(fn[, selector, row, col])

Apply a function to all smith objects that satisfy the specified selection criteria

for_each_ternary(fn[, selector, row, col])

Apply a function to all ternary objects that satisfy the specified selection criteria

for_each_trace(fn[, selector, row, col, …])

Apply a function to all traces that satisfy the specified selection criteria

for_each_xaxis(fn[, selector, row, col])

Apply a function to all xaxis objects that satisfy the specified selection criteria

for_each_yaxis(fn[, selector, row, col, …])

Apply a function to all yaxis objects that satisfy the specified selection criteria

full_figure_for_development([warn, as_dict])

Compute default values for all attributes not specified in the input figure and returns the output as a “full” figure.

get_subplot(row, col[, secondary_y])

Return an object representing the subplot at the specified row and column.

plotly_relayout(relayout_data, **kwargs)

Perform a Plotly relayout operation on the figure’s layout

plotly_restyle(restyle_data[, trace_indexes])

Perform a Plotly restyle operation on the figure’s traces

plotly_update([restyle_data, relayout_data, …])

Perform a Plotly update operation on the figure.

pop(key, *args)

Remove the value associated with the specified key and return it

print_grid()

Print a visual layout of the figure’s axes arrangement.

select_annotations([selector, row, col, …])

Select annotations from a particular subplot cell and/or annotations that satisfy custom selection criteria.

select_coloraxes([selector, row, col])

Select coloraxis subplot objects from a particular subplot cell and/or coloraxis subplot objects that satisfy custom selection criteria.

select_geos([selector, row, col])

Select geo subplot objects from a particular subplot cell and/or geo subplot objects that satisfy custom selection criteria.

select_layout_images([selector, row, col, …])

Select images from a particular subplot cell and/or images that satisfy custom selection criteria.

select_legends([selector, row, col])

Select legend subplot objects from a particular subplot cell and/or legend subplot objects that satisfy custom selection criteria.

select_mapboxes([selector, row, col])

Select mapbox subplot objects from a particular subplot cell and/or mapbox subplot objects that satisfy custom selection criteria.

select_maps([selector, row, col])

Select map subplot objects from a particular subplot cell and/or map subplot objects that satisfy custom selection criteria.

select_polars([selector, row, col])

Select polar subplot objects from a particular subplot cell and/or polar subplot objects that satisfy custom selection criteria.

select_scenes([selector, row, col])

Select scene subplot objects from a particular subplot cell and/or scene subplot objects that satisfy custom selection criteria.

select_selections([selector, row, col, …])

Select selections from a particular subplot cell and/or selections that satisfy custom selection criteria.

select_shapes([selector, row, col, secondary_y])

Select shapes from a particular subplot cell and/or shapes that satisfy custom selection criteria.

select_smiths([selector, row, col])

Select smith subplot objects from a particular subplot cell and/or smith subplot objects that satisfy custom selection criteria.

select_ternaries([selector, row, col])

Select ternary subplot objects from a particular subplot cell and/or ternary subplot objects that satisfy custom selection criteria.

select_traces([selector, row, col, secondary_y])

Select traces from a particular subplot cell and/or traces that satisfy custom selection criteria.

select_xaxes([selector, row, col])

Select xaxis subplot objects from a particular subplot cell and/or xaxis subplot objects that satisfy custom selection criteria.

select_yaxes([selector, row, col, secondary_y])

Select yaxis subplot objects from a particular subplot cell and/or yaxis subplot objects that satisfy custom selection criteria.

set_subplots([rows, cols])

Add subplots to this figure.

show(*args, **kwargs)

Show a figure using either the default renderer(s) or the renderer(s) specified by the renderer argument

to_dict()

Convert figure to a dictionary

to_html(*args, **kwargs)

Convert a figure to an HTML string representation.

to_image(*args, **kwargs)

Convert a figure to a static image bytes string

to_json(*args, **kwargs)

Convert a figure to a JSON string representation

to_ordered_dict([skip_uid])

to_plotly_json()

Convert figure to a JSON representation as a Python dict

update([dict1, overwrite])

Update the properties of the figure with a dict and/or with keyword arguments.

update_annotations([patch, selector, row, …])

Perform a property update operation on all annotations that satisfy the specified selection criteria

update_coloraxes([patch, selector, …])

Perform a property update operation on all coloraxis objects that satisfy the specified selection criteria

update_geos([patch, selector, overwrite, …])

Perform a property update operation on all geo objects that satisfy the specified selection criteria

update_layout([dict1, overwrite])

Update the properties of the figure’s layout with a dict and/or with keyword arguments.

update_layout_images([patch, selector, row, …])

Perform a property update operation on all images that satisfy the specified selection criteria

update_legends([patch, selector, overwrite, …])

Perform a property update operation on all legend objects that satisfy the specified selection criteria

update_mapboxes([patch, selector, …])

Perform a property update operation on all mapbox objects that satisfy the specified selection criteria

update_maps([patch, selector, overwrite, …])

Perform a property update operation on all map objects that satisfy the specified selection criteria

update_polars([patch, selector, overwrite, …])

Perform a property update operation on all polar objects that satisfy the specified selection criteria

update_scenes([patch, selector, overwrite, …])

Perform a property update operation on all scene objects that satisfy the specified selection criteria

update_selections([patch, selector, row, …])

Perform a property update operation on all selections that satisfy the specified selection criteria

update_shapes([patch, selector, row, col, …])

Perform a property update operation on all shapes that satisfy the specified selection criteria

update_smiths([patch, selector, overwrite, …])

Perform a property update operation on all smith objects that satisfy the specified selection criteria

update_ternaries([patch, selector, …])

Perform a property update operation on all ternary objects that satisfy the specified selection criteria

update_traces([patch, selector, row, col, …])

Perform a property update operation on all traces that satisfy the specified selection criteria

update_xaxes([patch, selector, overwrite, …])

Perform a property update operation on all xaxis objects that satisfy the specified selection criteria

update_yaxes([patch, selector, overwrite, …])

Perform a property update operation on all yaxis objects that satisfy the specified selection criteria

write_html(*args, **kwargs)

Write a figure to an HTML file representation

write_image(*args, **kwargs)

Convert a figure to a static image and write it to a file or writeable object

write_json(*args, **kwargs)

Convert a figure to JSON and write it to a file or writeable object

Attributes

data

The data property is a tuple of the figure’s trace objects

frames

The frames property is a tuple of the figure’s frame objects

layout

The layout property of the figure