Table of Contents
Contents

fiftyone.core.plots.plotly¶

Plotly plots.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Functions:

plot_confusion_matrix(confusion_matrix, labels)

Plots a confusion matrix.

plot_regressions(ytrue, ypred[, samples, …])

Plots the given regression results.

plot_pr_curve(precision, recall[, …])

Plots a precision-recall (PR) curve.

plot_pr_curves(precisions, recall, classes)

Plots a set of per-class precision-recall (PR) curves.

plot_roc_curve(fpr, tpr[, thresholds, …])

Plots a receiver operating characteristic (ROC) curve.

lines([x, y, samples, ids, link_field, …])

Plots the given lines(s) data.

scatterplot(points[, samples, ids, …])

Generates an interactive scatterplot of the given points.

location_scatterplot([locations, samples, …])

Generates an interactive scatterplot of the given location coordinates with a map rendered in the background of the plot.

get_colormap(colorscale[, n, hex_strs])

Generates a continuous colormap with the specified number of colors from the given plotly colorscale.

Classes:

PlotlyWidgetMixin(widget)

Mixin for Plotly plots that use widgets to display in Jupyter notebooks.

PlotlyNotebookPlot(figure)

A wrapper around a Plotly plot for Jupyter notebook contexts that allows it to be replaced with a screenshot by calling freeze().

PlotlyInteractivePlot(widget, **kwargs)

Base class for fiftyone.core.plots.base.InteractivePlot instances with Plotly backends.

InteractiveScatter(figure, **kwargs)

Wrapper class that turns a Plotly figure containing one or more scatter-type traces into an fiftyone.core.plots.base.InteractivePlot.

InteractiveHeatmap(Z, ids[, xlabels, …])

An interactive Plotly heatmap.
fiftyone.core.plots.plotly.plot_confusion_matrix(confusion_matrix, labels, ids=None, samples=None, eval_key=None, gt_field=None, pred_field=None, colorscale='oranges', log_colorscale=False, title=None, **kwargs)¶

Plots a confusion matrix.

If ids are provided, this method returns a InteractiveHeatmap that you can attach to an App session via its fiftyone.core.session.Session.plots attribute, which will automatically sync the session’s view with the currently selected cells in the confusion matrix.

Parameters

  • confusion_matrix – a num_true x num_preds confusion matrix

  • labels – a max(num_true, num_preds) array-like of class labels

  • ids (None) – an array-like of same shape as confusion_matrix whose elements are array-likes of label IDs corresponding to each cell

  • samples (None) – the fiftyone.core.collections.SampleCollection for which the confusion matrix was generated. Only used when ids are also provided to update an attached session

  • eval_key (None) – the evaluation key of the evaluation

  • gt_field (None) – the name of the ground truth field

  • pred_field (None) – the name of the predictions field

  • colorscale ("oranges") – a plotly colorscale to use. See https://plotly.com/python/colorscales for options

  • log_colorscale (False) – whether to apply the colorscale on a log scale. This is useful to better visualize variations in smaller values when large values are also present

  • title (None) – a title for the plot

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

Returns

one of the following

fiftyone.core.plots.plotly.plot_regressions(ytrue, ypred, samples=None, ids=None, labels=None, sizes=None, classes=None, gt_field=None, pred_field=None, figure=None, best_fit_label=None, marker_size=None, title=None, labels_title=None, sizes_title=None, show_colorbar_title=None, **kwargs)¶

Plots the given regression results.

If IDs are provided and you are working in a notebook environment with the default plotly backend, this method returns an InteractiveScatter plot that you can attach to an App session via its fiftyone.core.session.Session.plots attribute, which will automatically sync the session’s view with the currently selected points in the plot.

Parameters

  • ytrue – an array-like of ground truth values

  • ypred – an array-like of predicted values

  • samples (None) – the fiftyone.core.collections.SampleCollection for which the results were generated. Only used by the “plotly” backend when IDs are provided

  • ids (None) – an array-like of IDs corresponding to the regressions

  • labels (None) –

    data to use to color the points. Can be any of the following:

  • sizes (None) –

    data to use to scale the sizes of the points. Can be any of the following:

  • classes (None) – a list of classes whose points to plot. Only applicable when labels contains strings. If provided, the element order of this list also controls the z-order and legend order of multitrace plots (first class is rendered first, and thus on the bottom, and appears first in the legend)

  • gt_field (None) – the name of the ground truth field

  • pred_field (None) – the name of the predictions field

  • figure (None) – a plotly.graph_objects.Figure to which to add the plot

  • best_fit_label (None) – a custom legend label for the best fit line

  • marker_size (None) – the marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points

  • title (None) – a title for the plot

  • labels_title (None) – a title string to use for labels in the tooltip and the colorbar title. By default, if labels is a field name, this name will be used, otherwise the colorbar will not have a title and the tooltip will use “label”

  • sizes_title (None) – a title string to use for sizes in the tooltip. By default, if sizes is a field name, this name will be used, otherwise the tooltip will use “size”

  • show_colorbar_title (None) – whether to show the colorbar title. By default, a title will be shown only if a value was passed to labels_title or an appropriate default can be inferred from the labels parameter

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

Returns

one of the following

fiftyone.core.plots.plotly.plot_pr_curve(precision, recall, thresholds=None, label=None, style='area', figure=None, title=None, **kwargs)¶

Plots a precision-recall (PR) curve.

Parameters

  • precision – an array-like of precision values

  • recall – an array-like of recall values

  • thresholds (None) – an array-like of decision thresholds

  • label (None) – a label for the curve

  • style ("area") – a plot style to use. Supported values are ("area", "line")

  • figure (None) – a plotly.graph_objects.Figure to which to add the plot

  • title (None) – a title for the plot

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

Returns

one of the following

  • a PlotlyNotebookPlot, if you are working in a Jupyter notebook

  • a plotly figure, otherwise

fiftyone.core.plots.plotly.plot_pr_curves(precisions, recall, classes, thresholds=None, figure=None, title=None, **kwargs)¶

Plots a set of per-class precision-recall (PR) curves.

Parameters

  • precisions – a num_classes x num_recalls array-like of per-class precision values

  • recall – an array-like of recall values

  • classes – the list of classes

  • thresholds (None) – a num_classes x num_recalls array-like of decision thresholds

  • figure (None) – a plotly.graph_objects.Figure to which to add the plots

  • title (None) – a title for the plot

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

Returns

one of the following

  • a PlotlyNotebookPlot, if you are working in a Jupyter notebook

  • a plotly figure, otherwise

fiftyone.core.plots.plotly.plot_roc_curve(fpr, tpr, thresholds=None, roc_auc=None, style='area', figure=None, title=None, **kwargs)¶

Plots a receiver operating characteristic (ROC) curve.

Parameters

  • fpr – an array-like of false positive rates

  • tpr – an array-like of true positive rates

  • thresholds (None) – an array-like of decision thresholds

  • roc_auc (None) – the area under the ROC curve

  • style ("area") – a plot style to use. Supported values are ("area", "line")

  • figure (None) – a plotly.graph_objects.Figure to which to add the plot

  • title (None) – a title for the plot

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

Returns

one of the following

  • a PlotlyNotebookPlot, if you are working in a Jupyter notebook

  • a plotly figure, otherwise

fiftyone.core.plots.plotly.lines(x=None, y=None, samples=None, ids=None, link_field=None, sizes=None, labels=None, colors=None, marker_size=None, figure=None, title=None, xaxis_title=None, yaxis_title=None, sizes_title=None, axis_equal=False, **kwargs)¶

Plots the given lines(s) data.

You can attach plots generated by this method to an App session via its fiftyone.core.session.Session.plots attribute, which will automatically sync the session’s view with the currently selected points in the plot. To enable this functionality, you must pass samples to this method.

You can use the sizes parameter to scale the sizes of the points.

Parameters

  • x (None) –

    the x data to plot. Can be any of the following:

    • an array-like of values

    • a num_lines x n array-like or list of length num_lines of array-likes of values for multiple line traces

    • the name of a sample field or embedded.field.name of samples from which to extract values for a single line

    • the name of a frame field or frames.embedded.field.name of samples from which to extract values for per-sample line traces

    • a fiftyone.core.expressions.ViewExpression that resolves to a list (one line plot) or list of lists (multiple line plots) of numeric values to compute from samples via fiftyone.core.collections.SampleCollection.values()

  • y (None) –

    the y data to plot. Can be any of the following:

    • an array-like of values

    • a num_lines x n array-like or list of length num_lines of array-likes of values for multiple line traces

    • the name of a sample field or embedded.field.name of samples from which to extract values for a single line

    • the name of a frame field or frames.embedded.field.name of samples from which to extract values for per-sample line traces

    • a fiftyone.core.expressions.ViewExpression that resolves to a list (one line plot) or list of lists (multiple line plots) of numeric values to compute from samples via fiftyone.core.collections.SampleCollection.values()

  • samples (None) – the fiftyone.core.collections.SampleCollection whose data is being visualized

  • ids (None) – an array-like of IDs of same shape as y. If not provided but samples are provided, the appropriate IDs will be extracted from the samples

  • link_field (None) –

    a field of samples whose data corresponds to y. Can be any of the following:

    • None, if the line data correspond to samples (single trace) or frames (multiple traces)

    • "frames", if the line data correspond to frames (multiple traces). This option exists only for consistency with other plotting methods; in practice, it will be automatically inferred whenever multiple traces are being plotted

    • the name of a fiftyone.core.labels.Label field, if the line data correspond to the labels in this field

  • sizes (None) –

    data to use to scale the sizes of the points. Can be any of the following:

  • labels (None) – a name or list of names for the line traces

  • colors (None) – a list of colors to use for the line traces. See https://plotly.com/python/colorscales for options

  • marker_size (None) – the marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points

  • figure (None) – a plotly.graph_objects.Figure to which to add the plot

  • title (None) – a title for the plot

  • xaxis_title (None) – an x-axis title

  • yaxis_title (None) – a y-axis title

  • sizes_title (None) – a title string to use for sizes in the tooltip. By default, if sizes is a field name, this name will be used, otherwise the tooltip will use “size”

  • axis_equal (False) – whether to set the axes to equal scale

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

Returns

one of the following

  • an InteractiveScatter, when IDs are available

  • a PlotlyNotebookPlot, if you’re working in a Jupyter notebook but the above conditions aren’t met

  • a plotly figure, otherwise

fiftyone.core.plots.plotly.scatterplot(points, samples=None, ids=None, link_field=None, labels=None, sizes=None, edges=None, classes=None, figure=None, multi_trace=None, marker_size=None, colorscale=None, log_colorscale=False, title=None, trace_title=None, labels_title=None, sizes_title=None, edges_title=None, show_colorbar_title=None, axis_equal=False, **kwargs)¶

Generates an interactive scatterplot of the given points.

You can attach plots generated by this method to an App session via its fiftyone.core.session.Session.plots attribute, which will automatically sync the session’s view with the currently selected points in the plot. To enable this functionality, you must pass samples to this method.

This method supports 2D or 3D visualizations, but interactive point selection is only available in 2D.

You can use the labels parameters to define a coloring for the points, and you can use the sizes parameter to scale the sizes of the points.

Parameters

  • points – a num_points x num_dims array-like of points

  • samples (None) – the fiftyone.core.collections.SampleCollection whose data is being visualized

  • ids (None) – an array-like of IDs corresponding to the points. If not provided but samples are provided, the appropriate IDs will be extracted from the samples

  • link_field (None) –

    a field of samples whose data corresponds to points. Can be any of the following:

    • None, if the points correspond to samples

    • "frames", if the points correspond to frames

    • the name of a fiftyone.core.labels.Label field, if the points correspond to the labels in this field

  • labels (None) –

    data to use to color the points. Can be any of the following:

  • sizes (None) –

    data to use to scale the sizes of the points. Can be any of the following:

  • edges (None) – a num_edges x 2 array of row indices into points defining undirected edges between points to render as a separate trace on the scatterplot

  • classes (None) – a list of classes whose points to plot. Only applicable when labels contains strings. If provided, the element order of this list also controls the z-order and legend order of multitrace plots (first class is rendered first, and thus on the bottom, and appears first in the legend)

  • figure (None) – a plotly.graph_objects.Figure to which to add the plot

  • multi_trace (None) – whether to render each class as a separate trace. Only applicable when labels contains strings. By default, this will be true if there are up to 25 classes

  • marker_size (None) – the marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points

  • colorscale (None) – a plotly colorscale to use. Only applicable when labels contains numeric data. See https://plotly.com/python/colorscales for options

  • log_colorscale (False) – whether to apply the colorscale on a log scale. This is useful to better visualize variations in smaller values when large values are also present

  • title (None) – a title for the plot

  • trace_title (None) – a name for the scatter trace. Only applicable when plotting a single trace

  • labels_title (None) – a title string to use for labels in the tooltip and the colorbar title. By default, if labels is a field name, this name will be used, otherwise the colorbar will not have a title and the tooltip will use “label”

  • sizes_title (None) – a title string to use for sizes in the tooltip. By default, if sizes is a field name, this name will be used, otherwise the tooltip will use “size”

  • edges_title (None) – a title string to use for edges in the legend. If none is provided, edges are not included in the legend

  • show_colorbar_title (None) – whether to show the colorbar title. By default, a title will be shown only if a value was passed to labels_title or an appropriate default can be inferred from the labels parameter

  • axis_equal (False) – whether to set the axes to equal scale

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

Returns

one of the following

  • an InteractiveScatter, for 2D points and when IDs are available

  • a PlotlyNotebookPlot, if you’re working in a Jupyter notebook but the above conditions aren’t met

  • a plotly figure, otherwise

fiftyone.core.plots.plotly.location_scatterplot(locations=None, samples=None, ids=None, labels=None, sizes=None, edges=None, classes=None, style=None, radius=None, figure=None, multi_trace=None, marker_size=None, colorscale=None, log_colorscale=False, title=None, trace_title=None, labels_title=None, sizes_title=None, edges_title=None, show_colorbar_title=None, map_type='roadmap', **kwargs)¶

Generates an interactive scatterplot of the given location coordinates with a map rendered in the background of the plot.

Location data is specified via the locations parameter.

You can attach plots generated by this method to an App session via its fiftyone.core.session.Session.plots attribute, which will automatically sync the session’s view with the currently selected points in the plot. To enable this functionality, you must pass samples to this method.

You can use the labels parameters to define a coloring for the points, and you can use the sizes parameter to scale the sizes of the points.

Parameters

  • locations (None) –

    the location data to plot. Can be any of the following:

    • None, in which case samples must have a single fiftyone.core.labels.GeoLocation field whose point attribute contains location data

    • a num_locations x 2 array-like of (longitude, latitude) coordinates

    • the name of a fiftyone.core.labels.GeoLocation field of samples with (longitude, latitude) coordinates in its point attribute

  • samples (None) – the fiftyone.core.collections.SampleCollection whose data is being visualized

  • ids (None) – an array-like of IDs corresponding to the locations. If not provided but samples are provided, the appropriate IDs will be extracted from the samples

  • labels (None) –

    data to use to color the points. Can be any of the following:

  • sizes (None) –

    data to use to scale the sizes of the points. Can be any of the following:

  • edges (None) – a num_edges x 2 array-like of row indices into locations defining undirected edges between points to render as a separate trace on the scatterplot

  • classes (None) – a list of classes whose points to plot. Only applicable when labels contains strings. If provided, the element order of this list also controls the z-order and legend order of multitrace plots (first class is rendered first, and thus on the bottom, and appears first in the legend)

  • style (None) – the plot style to use. Only applicable when the color data is numeric. Supported values are ("scatter", "density")

  • radius (None) – the radius of influence of each lat/lon point. Only applicable when style is “density”. Larger values will make density plots smoother and less detailed

  • figure (None) – a plotly.graph_objects.Figure to which to add the plot

  • multi_trace (None) – whether to render each class as a separate trace. Only applicable when labels contains strings. By default, this will be true if there are up to 25 classes

  • marker_size (None) – the marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points

  • colorscale (None) – a plotly colorscale to use. Only applicable when labels contains numeric data. See https://plotly.com/python/colorscales for options

  • log_colorscale (False) – whether to apply the colorscale on a log scale. This is useful to better visualize variations in smaller values when large values are also present

  • title (None) – a title for the plot

  • trace_title (None) – a name for the scatter trace. Only applicable when plotting a single trace

  • labels_title (None) – a title string to use for labels in the tooltip and the colorbar title. By default, if labels is a field name, this name will be used, otherwise the colorbar will not have a title and the tooltip will use “label”

  • sizes_title (None) – a title string to use for sizes in the tooltip. By default, if sizes is a field name, this name will be used, otherwise the tooltip will use “size”

  • edges_title (None) – a title string to use for edges in the legend. If none is provided, edges are not included in the legend

  • show_colorbar_title (None) – whether to show the colorbar title. By default, a title will be shown only if a value was passed to labels_title or an appropriate default can be inferred from the labels parameter

  • map_type ("satellite") – the map type to render. Supported values are ("roadmap", "satellite")

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

Returns

one of the following

fiftyone.core.plots.plotly.get_colormap(colorscale, n=256, hex_strs=False)¶

Generates a continuous colormap with the specified number of colors from the given plotly colorscale.

The provided colorscale can be any of the following:

  • The string name of any colorscale recognized by plotly. See https://plotly.com/python/colorscales for possible options

  • A manually-defined colorscale like the following:

    [
    [0.000, "rgb(165,0,38)"],
    [0.111, "rgb(215,48,39)"],
    [0.222, "rgb(244,109,67)"],
    [0.333, "rgb(253,174,97)"],
    [0.444, "rgb(254,224,144)"],
    [0.555, "rgb(224,243,248)"],
    [0.666, "rgb(171,217,233)"],
    [0.777, "rgb(116,173,209)"],
    [0.888, "rgb(69,117,180)"],
    [1.000, "rgb(49,54,149)"],
]

The colorscale will be sampled evenly at the required resolution in order to generate the colormap.

Parameters

  • colorscale – a valid colorscale. See above for possible options

  • n (256) – the desired number of colors

  • hex_strs (False) – whether to return #RRGGBB hex strings rather than (R, G, B) tuples

Returns

a list of (R, G, B) tuples in [0, 255], or, if hex_strs is True, a list of #RRGGBB strings

class fiftyone.core.plots.plotly.PlotlyWidgetMixin(widget)¶

Bases: object

Mixin for Plotly plots that use widgets to display in Jupyter notebooks.

This class can still be used in non-Jupyter notebook environments, but the resulting figures will not be interactive.

Parameters

widget – a plotly.graph_objects.FigureWidget

Methods:

save(path[, width, height, scale])

Saves the plot as an image or HTML.
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

class fiftyone.core.plots.plotly.PlotlyNotebookPlot(figure)¶

Bases: fiftyone.core.plots.plotly.PlotlyWidgetMixin, fiftyone.core.plots.base.Plot

A wrapper around a Plotly plot for Jupyter notebook contexts that allows it to be replaced with a screenshot by calling freeze().

Parameters

figure – a plotly.graph_objects.Figure

Attributes:

is_frozen

Whether this plot is currently frozen.

Methods:

update_layout(**kwargs)

Updates the layout of the plot.

show(**kwargs)

Shows the plot.

freeze()

Freezes the plot, replacing it with a static image.

save(path[, width, height, scale])

Saves the plot as an image or HTML.
property is_frozen¶

Whether this plot is currently frozen.

update_layout(**kwargs)¶

Updates the layout of the plot.

Parameters

**kwargs – valid arguments for plotly.graph_objects.Figure.update_layout()

show(**kwargs)¶

Shows the plot.

Parameters

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

freeze()¶

Freezes the plot, replacing it with a static image.

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

class fiftyone.core.plots.plotly.PlotlyInteractivePlot(widget, **kwargs)¶

Bases: fiftyone.core.plots.plotly.PlotlyWidgetMixin, fiftyone.core.plots.base.InteractivePlot

Base class for fiftyone.core.plots.base.InteractivePlot instances with Plotly backends.

Parameters

Methods:

update_layout(**kwargs)

Updates the layout of the plot.

show(**kwargs)

Shows the plot.

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

recommend_link_type([label_field, samples])

Recommends a link type for the given info.

register_disconnect_callback(callback)

Registers a callback that can disconnect this plot from a SessionPlot connected to it.

register_selection_callback(callback)

Registers a selection callback for this plot.

register_sync_callback(callback)

Registers a callback that can sync this plot with a SessionPlot connected to it.

reset()

Resets the plot to its default state.

save(path[, width, height, scale])

Saves the plot as an image or HTML.

select_ids(ids[, view])

Selects the points with the given IDs in this plot.

Attributes:

init_view

A fiftyone.core.collections.SampleCollection defining the initial view from which to derive selection views when points are selected in the plot.

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.

selected_ids

A list of IDs of the currently selected points.

selection_mode

The current selection mode of the plot.

supports_session_updates

Whether this plot supports automatic updates in response to session changes.
update_layout(**kwargs)¶

Updates the layout of the plot.

Parameters

**kwargs – valid arguments for plotly.graph_objects.Figure.update_layout()

show(**kwargs)¶

Shows the 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 init_view¶

A fiftyone.core.collections.SampleCollection defining the initial view from which to derive selection views when points are selected in the plot.

This view will also be shown when the plot is in its default state (no selection).

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.

The link type between this plot and a connected session.

Recommends a link type for the given info.

Parameters
Returns

a (link_type, label_fields, selection_mode, init_fcn) tuple

register_disconnect_callback(callback)¶

Registers a callback that can disconnect this plot from a SessionPlot connected to it.

The typical use case for this function is to serve as the callback for a disconnect button on the plot.

Parameters

callback – a function with no arguments

register_selection_callback(callback)¶

Registers a selection callback for this plot.

Selection callbacks are functions that take a single argument containing the list of currently selected IDs.

If a selection callback is registered, this plot should invoke it each time their selection is updated.

Parameters

callback – a selection callback

register_sync_callback(callback)¶

Registers a callback that can sync this plot with a SessionPlot connected to it.

The typical use case for this function is to serve as the callback for a sync button on the plot.

Parameters

callback – a function with no arguments

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

select_ids(ids, view=None)¶

Selects the points with the given IDs in this plot.

Parameters

  • ids – a list of IDs, or None to reset the plot to its default state

  • view (None) – the fiftyone.core.view.DatasetView corresponding to the given IDs, if available

property selected_ids¶

A list of IDs of the currently selected points.

An empty list means all points are deselected, and None means default state (nothing selected or unselected).

If the plot is not connected, returns None.

property selection_mode¶

The current selection mode of the plot.

This property controls how the current view is updated in response to updates from InteractivePlot instances that are linked to labels or frames.

When link_type is "frames", the supported values are:

  • "select": show video samples with labels only for the selected frames

  • "match": show unfiltered video samples containing at least one selected frame

  • "frames": show only the selected frames in a frames view

When link_type is "labels", the supported values are:

  • "select": show only the selected labels

  • "match": show unfiltered samples containing at least one selected label

  • "patches": show the selected labels in a patches view

Note

In order to use "patches" selection mode, you must have provided an init_fcn when constructing this plot that defines how to create the base patches view. This usually involves to_patches() or to_evaluation_patches()

Note

In order to use "frames" selection mode, you must have provided an init_fcn when constructing this plot that defines how to create the base frames view. This usually involves to_frames()

property supports_session_updates¶

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

class fiftyone.core.plots.plotly.InteractiveScatter(figure, **kwargs)¶

Bases: fiftyone.core.plots.plotly.PlotlyInteractivePlot

Wrapper class that turns a Plotly figure containing one or more scatter-type traces into an fiftyone.core.plots.base.InteractivePlot.

This wrapper responds to selection and deselection events (if available) triggered on the figure’s traces via Plotly’s lasso and box selector tools.

Traces whose customdata attribute contain lists/arrays are assumed to contain the IDs of the points in the trace. Traces with no customdata are allowed, but will not have any selection events.

Parameters

Attributes:

supports_session_updates

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

init_view

A fiftyone.core.collections.SampleCollection defining the initial view from which to derive selection views when points are selected in the plot.

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.

selected_ids

A list of IDs of the currently selected points.

selection_mode

The current selection mode of the plot.

Methods:

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

recommend_link_type([label_field, samples])

Recommends a link type for the given info.

register_disconnect_callback(callback)

Registers a callback that can disconnect this plot from a SessionPlot connected to it.

register_selection_callback(callback)

Registers a selection callback for this plot.

register_sync_callback(callback)

Registers a callback that can sync this plot with a SessionPlot connected to it.

reset()

Resets the plot to its default state.

save(path[, width, height, scale])

Saves the plot as an image or HTML.

select_ids(ids[, view])

Selects the points with the given IDs in this plot.

show(**kwargs)

Shows the plot.

update_layout(**kwargs)

Updates the layout of the plot.
property 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 init_view¶

A fiftyone.core.collections.SampleCollection defining the initial view from which to derive selection views when points are selected in the plot.

This view will also be shown when the plot is in its default state (no selection).

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.

The link type between this plot and a connected session.

Recommends a link type for the given info.

Parameters
Returns

a (link_type, label_fields, selection_mode, init_fcn) tuple

register_disconnect_callback(callback)¶

Registers a callback that can disconnect this plot from a SessionPlot connected to it.

The typical use case for this function is to serve as the callback for a disconnect button on the plot.

Parameters

callback – a function with no arguments

register_selection_callback(callback)¶

Registers a selection callback for this plot.

Selection callbacks are functions that take a single argument containing the list of currently selected IDs.

If a selection callback is registered, this plot should invoke it each time their selection is updated.

Parameters

callback – a selection callback

register_sync_callback(callback)¶

Registers a callback that can sync this plot with a SessionPlot connected to it.

The typical use case for this function is to serve as the callback for a sync button on the plot.

Parameters

callback – a function with no arguments

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

select_ids(ids, view=None)¶

Selects the points with the given IDs in this plot.

Parameters

  • ids – a list of IDs, or None to reset the plot to its default state

  • view (None) – the fiftyone.core.view.DatasetView corresponding to the given IDs, if available

property selected_ids¶

A list of IDs of the currently selected points.

An empty list means all points are deselected, and None means default state (nothing selected or unselected).

If the plot is not connected, returns None.

property selection_mode¶

The current selection mode of the plot.

This property controls how the current view is updated in response to updates from InteractivePlot instances that are linked to labels or frames.

When link_type is "frames", the supported values are:

  • "select": show video samples with labels only for the selected frames

  • "match": show unfiltered video samples containing at least one selected frame

  • "frames": show only the selected frames in a frames view

When link_type is "labels", the supported values are:

  • "select": show only the selected labels

  • "match": show unfiltered samples containing at least one selected label

  • "patches": show the selected labels in a patches view

Note

In order to use "patches" selection mode, you must have provided an init_fcn when constructing this plot that defines how to create the base patches view. This usually involves to_patches() or to_evaluation_patches()

Note

In order to use "frames" selection mode, you must have provided an init_fcn when constructing this plot that defines how to create the base frames view. This usually involves to_frames()

show(**kwargs)¶

Shows the plot.

Parameters

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

update_layout(**kwargs)¶

Updates the layout of the plot.

Parameters

**kwargs – valid arguments for plotly.graph_objects.Figure.update_layout()

class fiftyone.core.plots.plotly.InteractiveHeatmap(Z, ids, xlabels=None, ylabels=None, zlim=None, values_title='count', gt_field=None, pred_field=None, colorscale=None, grid_opacity=0.1, bg_opacity=0.25, **kwargs)¶

Bases: fiftyone.core.plots.plotly.PlotlyInteractivePlot

An interactive Plotly heatmap.

Unfortunately, the Plotly team has not gotten around to adding native selection utilities to plot types such as heatmaps: https://github.com/plotly/plotly.js/issues/170.

In lieu of this feature, we provide a homebrewed heatmap that supports two types of interactivity:

  • Individual cells can be selected by clicking on them

  • Groups of cells can be lasso- or box-selected by including their cell centers in a selection

The following events will cause the selection to be cleared:

  • Clicking any cell, if there are currently multiple cells selected

  • Clicking the selected cell, if there is only one cell selected

When heatmap contents are selected via InteractiveHeatmap.select_ids(), the heatmap is updated to reflect the proportions of each cell included in the selection.

Parameters

  • Z – a num_cols x num_rows array-like of heatmap values

  • ids – an array-like of same shape as Z whose elements contain lists of IDs for the heatmap cells

  • xlabels (None) – a num_rows array of x labels

  • ylabels (None) – a num_cols array of y labels

  • zlim (None) – a [zmin, zmax] limit to use for the colorbar

  • values_title ("count") – the semantic meaning of the heatmap values. Used for tooltips

  • gt_field (None) – the name of the ground truth field, if known. Used for tooltips

  • pred_field (None) – the name of the predictions field, if known. Used for tooltips

  • colorscale (None) – a plotly colorscale to use

  • grid_opacity (0.1) – an opacity value for the grid points

  • bg_opacity (0.25) – an opacity value for background (unselected) cells

  • **kwargs – keyword arguments for the fiftyone.core.plots.base.InteractivePlot constructor

Attributes:

supports_session_updates

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

init_view

A fiftyone.core.collections.SampleCollection defining the initial view from which to derive selection views when points are selected in the plot.

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.

selected_ids

A list of IDs of the currently selected points.

selection_mode

The current selection mode of the plot.

Methods:

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

recommend_link_type([label_field, samples])

Recommends a link type for the given info.

register_disconnect_callback(callback)

Registers a callback that can disconnect this plot from a SessionPlot connected to it.

register_selection_callback(callback)

Registers a selection callback for this plot.

register_sync_callback(callback)

Registers a callback that can sync this plot with a SessionPlot connected to it.

reset()

Resets the plot to its default state.

save(path[, width, height, scale])

Saves the plot as an image or HTML.

select_ids(ids[, view])

Selects the points with the given IDs in this plot.

show(**kwargs)

Shows the plot.

update_layout(**kwargs)

Updates the layout of the plot.
property supports_session_updates¶

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

property init_view¶

A fiftyone.core.collections.SampleCollection defining the initial view from which to derive selection views when points are selected in the plot.

This view will also be shown when the plot is in its default state (no selection).

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.

The link type between this plot and a connected session.

Recommends a link type for the given info.

Parameters
Returns

a (link_type, label_fields, selection_mode, init_fcn) tuple

register_disconnect_callback(callback)¶

Registers a callback that can disconnect this plot from a SessionPlot connected to it.

The typical use case for this function is to serve as the callback for a disconnect button on the plot.

Parameters

callback – a function with no arguments

register_selection_callback(callback)¶

Registers a selection callback for this plot.

Selection callbacks are functions that take a single argument containing the list of currently selected IDs.

If a selection callback is registered, this plot should invoke it each time their selection is updated.

Parameters

callback – a selection callback

register_sync_callback(callback)¶

Registers a callback that can sync this plot with a SessionPlot connected to it.

The typical use case for this function is to serve as the callback for a sync button on the plot.

Parameters

callback – a function with no arguments

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

select_ids(ids, view=None)¶

Selects the points with the given IDs in this plot.

Parameters

  • ids – a list of IDs, or None to reset the plot to its default state

  • view (None) – the fiftyone.core.view.DatasetView corresponding to the given IDs, if available

property selected_ids¶

A list of IDs of the currently selected points.

An empty list means all points are deselected, and None means default state (nothing selected or unselected).

If the plot is not connected, returns None.

property selection_mode¶

The current selection mode of the plot.

This property controls how the current view is updated in response to updates from InteractivePlot instances that are linked to labels or frames.

When link_type is "frames", the supported values are:

  • "select": show video samples with labels only for the selected frames

  • "match": show unfiltered video samples containing at least one selected frame

  • "frames": show only the selected frames in a frames view

When link_type is "labels", the supported values are:

  • "select": show only the selected labels

  • "match": show unfiltered samples containing at least one selected label

  • "patches": show the selected labels in a patches view

Note

In order to use "patches" selection mode, you must have provided an init_fcn when constructing this plot that defines how to create the base patches view. This usually involves to_patches() or to_evaluation_patches()

Note

In order to use "frames" selection mode, you must have provided an init_fcn when constructing this plot that defines how to create the base frames view. This usually involves to_frames()

show(**kwargs)¶

Shows the plot.

Parameters

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

update_layout(**kwargs)¶

Updates the layout of the plot.

Parameters

**kwargs – valid arguments for plotly.graph_objects.Figure.update_layout()