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: fiftyone.core.plots.plotly.PlotlyWidgetMixin, fiftyone.core.plots.base.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.graph_objects.Figure.to_image or 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: fiftyone.core.plots.views.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.graph_objects.Figure.to_image or 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: fiftyone.core.plots.views.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.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.graph_objects.Figure.to_image or 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: fiftyone.core.plots.views.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.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.graph_objects.Figure.to_image or 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