fiftyone.core.plots.views

Plotly-powered view plots.

Copyright 2017-2025, Voxel51, Inc.

voxel51.com

Classes:

PlotlyViewPlot(widget[, init_view])	Base class for ViewPlot instances with Plotly backends.
ViewGrid(plots[, shape, hgap, vgap, init_view])	A grid of PlotlyViewPlot instances.
CategoricalHistogram(field_or_expr[, expr, ...])	A histogram of a categorial field.
NumericalHistogram(field_or_expr[, expr, ...])	A histogram of a numerical field.

class fiftyone.core.plots.views.PlotlyViewPlot(widget, init_view=None)

Bases: PlotlyWidgetMixin, ViewPlot

Base class for ViewPlot instances with Plotly backends.

Parameters:

• widget – a plotly.graph_objects.FigureWidget

• init_view (None) – an optional initial fiftyone.core.collections.SampleCollection to load

Methods:

show(**kwargs)	Shows this plot.
connect()	Connects this plot, if necessary.
disconnect()	Disconnects the plot, if necessary.
freeze()	Freezes the plot, replacing it with a static image.
reset()	Resets the plot to its default state.
save(path[, width, height, scale])	Saves the plot as an image or HTML.
update_view(view[, agg_results])	Updates the plot based on the provided view.

Attributes:

is_connected	Whether this plot is currently connected.
is_disconnected	Whether this plot is currently disconnected.
is_frozen	Whether this plot is currently frozen.
link_type	The link type between this plot and a connected session.
supports_session_updates	Whether this plot supports automatic updates in response to session changes.

show(**kwargs)

Shows this plot.

Parameters:

**kwargs – optional parameters for plotly.graph_objects.Figure.update_layout()

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

property is_connected

Whether this plot is currently connected.

property is_disconnected

Whether this plot is currently disconnected.

property is_frozen

Whether this plot is currently frozen.

property link_type

The link type between this plot and a connected session.

reset()

Resets the plot to its default state.

save(path, width=None, height=None, scale=None, **kwargs)

Saves the plot as an image or HTML.

Parameters:

• path – the path to write the image or HTML

• width (None) – a desired width in pixels when saving as an image. By default, the layout width is used

• height (None) – a desired height in pixels when saving as an image. By default, the layout height is used

• scale (None) – a scale factor to apply to the layout dimensions. By default, this is 1.0

• **kwargs – keyword arguments for plotly:plotly.graph_objects.Figure.to_image() or plotly:plotly.graph_objects.Figure.write_html()

property supports_session_updates

Whether this plot supports automatic updates in response to session changes.

update_view(view, agg_results=None)

Updates the plot based on the provided view.

Parameters:

• view – a fiftyone.core.collections.SampleCollection

• agg_results (None) – a list of pre-computed aggregation results

class fiftyone.core.plots.views.ViewGrid(plots, shape=None, hgap=None, vgap=None, init_view=None, **kwargs)

Bases: PlotlyViewPlot

A grid of PlotlyViewPlot instances.

Parameters:

• plots – a PlotlyViewPlot or iterable of PlotlyViewPlot instances

• shape (None) – the (rows, cols) shape to use for the grid

• hgap (None) – a horizontal spacing between the subplots, in [0, 1]

• vgap (None) – a vertical spacing between the subplots, in [0, 1]

• init_view (None) – an optional initial fiftyone.core.collections.SampleCollection to load

• **kwargs – optional parameters for plotly.graph_objects.Figure.update_layout()

Methods:

connect()	Connects this plot, if necessary.
disconnect()	Disconnects the plot, if necessary.
freeze()	Freezes the plot, replacing it with a static image.
reset()	Resets the plot to its default state.
save(path[, width, height, scale])	Saves the plot as an image or HTML.
show(**kwargs)	Shows this plot.
update_view(view[, agg_results])	Updates the plot based on the provided view.

Attributes:

is_connected	Whether this plot is currently connected.
is_disconnected	Whether this plot is currently disconnected.
is_frozen	Whether this plot is currently frozen.
link_type	The link type between this plot and a connected session.
supports_session_updates	Whether this plot supports automatic updates in response to session changes.

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

property is_connected

Whether this plot is currently connected.

property is_disconnected

Whether this plot is currently disconnected.

property is_frozen

Whether this plot is currently frozen.

property link_type

The link type between this plot and a connected session.

reset()

Resets the plot to its default state.

save(path, width=None, height=None, scale=None, **kwargs)

Saves the plot as an image or HTML.

Parameters:

• path – the path to write the image or HTML

• width (None) – a desired width in pixels when saving as an image. By default, the layout width is used

• height (None) – a desired height in pixels when saving as an image. By default, the layout height is used

• scale (None) – a scale factor to apply to the layout dimensions. By default, this is 1.0

• **kwargs – keyword arguments for plotly:plotly.graph_objects.Figure.to_image() or plotly:plotly.graph_objects.Figure.write_html()

show(**kwargs)

Shows this plot.

Parameters:

**kwargs – optional parameters for plotly.graph_objects.Figure.update_layout()

property supports_session_updates

Whether this plot supports automatic updates in response to session changes.

update_view(view, agg_results=None)

Updates the plot based on the provided view.

Parameters:

• view – a fiftyone.core.collections.SampleCollection

• agg_results (None) – a list of pre-computed aggregation results

class fiftyone.core.plots.views.CategoricalHistogram(field_or_expr, expr=None, order='alphabetical', xlabel=None, log=None, bargap=None, color=None, opacity=None, init_view=None, **kwargs)

Bases: PlotlyViewPlot

A histogram of a categorial field.

Parameters:

• field_or_expr – a field name, embedded.field.name, fiftyone.core.expressions.ViewExpression, or MongoDB expression defining the field or expression to plot

• expr (None) –

  an optional fiftyone.core.expressions.ViewExpression or MongoDB expression to apply to field_or_expr (which must be a field) before plotting

• order ("alphabetical") – the x-axis ordering strategy to use. Can be “alphabetical” to sort by field value, or “frequency” to sort in descending order of frequency, or a function suitable for sorted(items, key=order), where items is a list of (value, count) tuples

• xlabel (None) – an optional x-label for the plot

• log (False) – whether to use a log scale y-axis

• bargap (None) – relative spacing between bars in [0, 1]

• color (None) – a color for the bars. Can be any color supported by plotly:plotly.graph_objects.bar.Marker.color()

• opacity (None) – an optional opacity for the bars in [0, 1]

• init_view (None) – an optional initial fiftyone.core.collections.SampleCollection to load

• **kwargs – optional parameters for plotly.graph_objects.Figure.update_layout()

Methods:

connect()	Connects this plot, if necessary.
disconnect()	Disconnects the plot, if necessary.
freeze()	Freezes the plot, replacing it with a static image.
reset()	Resets the plot to its default state.
save(path[, width, height, scale])	Saves the plot as an image or HTML.
show(**kwargs)	Shows this plot.
update_view(view[, agg_results])	Updates the plot based on the provided view.

Attributes:

is_connected	Whether this plot is currently connected.
is_disconnected	Whether this plot is currently disconnected.
is_frozen	Whether this plot is currently frozen.
link_type	The link type between this plot and a connected session.
supports_session_updates	Whether this plot supports automatic updates in response to session changes.

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

property is_connected

Whether this plot is currently connected.

property is_disconnected

Whether this plot is currently disconnected.

property is_frozen

Whether this plot is currently frozen.

property link_type

The link type between this plot and a connected session.

reset()

Resets the plot to its default state.

save(path, width=None, height=None, scale=None, **kwargs)

Saves the plot as an image or HTML.

Parameters:

• path – the path to write the image or HTML

• width (None) – a desired width in pixels when saving as an image. By default, the layout width is used

• height (None) – a desired height in pixels when saving as an image. By default, the layout height is used

• scale (None) – a scale factor to apply to the layout dimensions. By default, this is 1.0

• **kwargs – keyword arguments for plotly:plotly.graph_objects.Figure.to_image() or plotly:plotly.graph_objects.Figure.write_html()

show(**kwargs)

Shows this plot.

Parameters:

**kwargs – optional parameters for plotly.graph_objects.Figure.update_layout()

property supports_session_updates

Whether this plot supports automatic updates in response to session changes.

update_view(view, agg_results=None)

Updates the plot based on the provided view.

Parameters:

• view – a fiftyone.core.collections.SampleCollection

• agg_results (None) – a list of pre-computed aggregation results

class fiftyone.core.plots.views.NumericalHistogram(field_or_expr, expr=None, bins=None, range=None, xlabel=None, log=None, color=None, opacity=None, init_view=None, **kwargs)

Bases: PlotlyViewPlot

A histogram of a numerical field.

Parameters:

• field_or_expr –

  a field name, embedded.field.name, fiftyone.core.expressions.ViewExpression, or MongoDB expression defining the field or expression to plot

• expr (None) –

  an optional fiftyone.core.expressions.ViewExpression or MongoDB expression to apply to field_or_expr (which must be a field) before plotting

• bins (None) – can be either an integer number of bins to generate or a monotonically increasing sequence specifying the bin edges to use. By default, 10 bins are created. If bins is an integer and no range is specified, bin edges are automatically computed from the bounds of the field

• range (None) – a (lower, upper) tuple specifying a range in which to generate equal-width bins. Only applicable when bins is an integer or None

• xlabel (None) – an optional x-label for the plot

• log (False) – whether to use a log scale y-axis

• color (None) – a color for the bars. Can be any color supported by plotly:plotly.graph_objects.bar.Marker.color()

• opacity (None) – an optional opacity for the bars in [0, 1]

• init_view (None) – an optional initial fiftyone.core.collections.SampleCollection to load

• **kwargs – optional parameters for plotly.graph_objects.Figure.update_layout()

Methods:

connect()	Connects this plot, if necessary.
disconnect()	Disconnects the plot, if necessary.
freeze()	Freezes the plot, replacing it with a static image.
reset()	Resets the plot to its default state.
save(path[, width, height, scale])	Saves the plot as an image or HTML.
show(**kwargs)	Shows this plot.
update_view(view[, agg_results])	Updates the plot based on the provided view.

Attributes:

is_connected	Whether this plot is currently connected.
is_disconnected	Whether this plot is currently disconnected.
is_frozen	Whether this plot is currently frozen.
link_type	The link type between this plot and a connected session.
supports_session_updates	Whether this plot supports automatic updates in response to session changes.

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

property is_connected

Whether this plot is currently connected.

property is_disconnected

Whether this plot is currently disconnected.

property is_frozen

Whether this plot is currently frozen.

property link_type

The link type between this plot and a connected session.

reset()

Resets the plot to its default state.

save(path, width=None, height=None, scale=None, **kwargs)

Saves the plot as an image or HTML.

Parameters:

• path – the path to write the image or HTML

• width (None) – a desired width in pixels when saving as an image. By default, the layout width is used

• height (None) – a desired height in pixels when saving as an image. By default, the layout height is used

• scale (None) – a scale factor to apply to the layout dimensions. By default, this is 1.0

• **kwargs – keyword arguments for plotly:plotly.graph_objects.Figure.to_image() or plotly:plotly.graph_objects.Figure.write_html()

show(**kwargs)

Shows this plot.

Parameters:

**kwargs – optional parameters for plotly.graph_objects.Figure.update_layout()

property supports_session_updates

Whether this plot supports automatic updates in response to session changes.

update_view(view, agg_results=None)

Updates the plot based on the provided view.

Parameters:

• view – a fiftyone.core.collections.SampleCollection

• agg_results (None) – a list of pre-computed aggregation results