fiftyone.core.plots.base#

Base plotting definitions.

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.

Classes:

Plot()

Base class for all plots.

ResponsivePlot(link_type)

Base class for all responsive plots that can push/pull updates to a linked object.

ViewPlot([init_view])

Base class for plots that can be automatically populated given a fiftyone.core.collections.SampleCollection instance.

InteractivePlot([link_type, init_view, ...])

Base class for plots that support selection of their points.
fiftyone.core.plots.base.plot_confusion_matrix(confusion_matrix, labels, ids=None, samples=None, eval_key=None, gt_field=None, pred_field=None, backend='plotly', **kwargs)#

Plots a confusion matrix.

If ids are provided and you are working in a notebook environment with the default plotly backend, this method returns an interactive fiftyone.core.plots.plotly.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 containing lists of IDs corresponding to each cell

  • samples (None) – the fiftyone.core.collections.SampleCollection for which the confusion matrix was generated

  • 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

  • backend ("plotly") – the plotting backend to use. Supported values are ("plotly", "matplotlib")

  • **kwargs –

    keyword arguments for the backend plotting method:

Returns:

one of the following

fiftyone.core.plots.base.plot_regressions(ytrue, ypred, samples=None, ids=None, labels=None, sizes=None, classes=None, gt_field=None, pred_field=None, backend='plotly', **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 interactive fiftyone.core.plots.plotly.InteractiveScatter 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 sample or frame IDs corresponding to the regressions. 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:

  • classes (None) – a list of classes whose points to plot. Only applicable when labels contains strings

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

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

  • backend ("plotly") – the plotting backend to use. Supported values are ("plotly", "matplotlib")

  • **kwargs –

    keyword arguments for the backend plotting method:

Returns:

one of the following

fiftyone.core.plots.base.plot_pr_curve(precision, recall, thresholds=None, label=None, backend='plotly', **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

  • backend ("plotly") – the plotting backend to use. Supported values are ("plotly", "matplotlib")

  • **kwargs –

    keyword arguments for the backend plotting method:

Returns:

one of the following

fiftyone.core.plots.base.plot_pr_curves(precisions, recall, classes, thresholds=None, backend='plotly', **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) – an num_classes x num_recalls array-like of decision thresholds

  • backend ("plotly") – the plotting backend to use. Supported values are ("plotly", "matplotlib")

  • **kwargs –

    keyword arguments for the backend plotting method:

Returns:

one of the following

fiftyone.core.plots.base.plot_roc_curve(fpr, tpr, thresholds=None, roc_auc=None, backend='plotly', **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

  • backend ("plotly") – the plotting backend to use. Supported values are ("plotly", "matplotlib")

  • **kwargs –

    keyword arguments for the backend plotting method:

Returns:

one of the following

fiftyone.core.plots.base.lines(x=None, y=None, samples=None, ids=None, link_field=None, sizes=None, backend='plotly', **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:

  • backend ("plotly") – the plotting backend to use. Supported values are ("plotly", "matplotlib")

  • **kwargs –

    keyword arguments for the backend plotting method:

Returns:

one of the following

fiftyone.core.plots.base.scatterplot(points, samples=None, ids=None, link_field=None, labels=None, sizes=None, classes=None, backend='plotly', **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 linked 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:

  • classes (None) – an list of classes whose points to plot. Only applicable when labels contains strings

  • backend ("plotly") – the plotting backend to use. Supported values are ("plotly", "matplotlib")

  • **kwargs –

    keyword arguments for the backend plotting method:

Returns:

one of the following

fiftyone.core.plots.base.location_scatterplot(locations=None, samples=None, ids=None, labels=None, sizes=None, classes=None, backend='plotly', **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:
Returns:

one of the following

class fiftyone.core.plots.base.Plot#

Bases: object

Base class for all plots.

Attributes:

is_frozen

Whether this plot is currently frozen.

Methods:

show(**kwargs)

Shows the plot.

save(path, **kwargs)

Saves the plot.

freeze()

Freezes the plot, replacing it with a static image.
property is_frozen#

Whether this plot is currently frozen.

show(**kwargs)#

Shows the plot.

Parameters:

**kwargs – subclass-specific keyword arguments

save(path, **kwargs)#

Saves the plot.

Parameters:

  • path – the path to write the plot

  • **kwargs – subclass-specific keyword arguments

freeze()#

Freezes the plot, replacing it with a static image.

Only applicable in notebook contexts.

class fiftyone.core.plots.base.ResponsivePlot(link_type)#

Bases: Plot

Base class for all responsive plots that can push/pull updates to a linked object.

Parameters:

link_type – the link type of the plot

Attributes:

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.

is_connected

Whether this plot is currently connected.

is_disconnected

Whether this plot is currently disconnected.

is_frozen

Whether this plot is currently frozen.

Methods:

connect()

Connects this plot, if necessary.

show(**kwargs)

Shows the plot.

reset()

Resets the plot to its default state.

freeze()

Freezes the plot, replacing it with a static image.

disconnect()

Disconnects the plot, if necessary.

save(path, **kwargs)

Saves the plot.

The link type between this plot and a connected session.

property supports_session_updates#

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

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.

connect()#

Connects this plot, if necessary.

show(**kwargs)#

Shows the plot.

The plot will be connected if necessary.

Parameters:

**kwargs – subclass-specific keyword arguments

reset()#

Resets the plot to its default state.

freeze()#

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

disconnect()#

Disconnects the plot, if necessary.

save(path, **kwargs)#

Saves the plot.

Parameters:

  • path – the path to write the plot

  • **kwargs – subclass-specific keyword arguments

class fiftyone.core.plots.base.ViewPlot(init_view=None)#

Bases: ResponsivePlot

Base class for plots that can be automatically populated given a fiftyone.core.collections.SampleCollection instance.

The state of ViewPlot instances can also be updated by external parties by calling its update_view() method.

Parameters:

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

Attributes:

supports_session_updates

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

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.

Methods:

update_view(view[, agg_results])

Updates the plot based on the provided view.

reset()

Resets the plot to its default state.

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

save(path, **kwargs)

Saves the plot.

show(**kwargs)

Shows the plot.
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:
reset()#

Resets the plot to its default state.

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.

save(path, **kwargs)#

Saves the plot.

Parameters:

  • path – the path to write the plot

  • **kwargs – subclass-specific keyword arguments

show(**kwargs)#

Shows the plot.

The plot will be connected if necessary.

Parameters:

**kwargs – subclass-specific keyword arguments

class fiftyone.core.plots.base.InteractivePlot(link_type='samples', init_view=None, label_fields=None, selection_mode=None, init_fcn=None)#

Bases: ResponsivePlot

Base class for plots that support selection of their points.

Whenever a selection is made in an InteractivePlot, the plot will invoke any selection callback(s) registered on it, reporting to its listeners the IDs of its selected points.

Conversely, the state of an InteractivePlot can be updated by external parties by calling its select_ids() method.

Parameters:

  • link_type ("samples") – whether this plot is linked to "samples", "frames", or "labels"

  • init_view (None) – a fiftyone.core.collections.SampleCollection defining an 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)

  • label_fields (None) – a label field or list of label fields to which points in this plot correspond. Only applicable when link_type == "labels"

  • selection_mode (None) – the initial selection mode to use when updating connected sessions in response to selections in this plot. See selection_mode() for details

  • init_fcn (None) – a function that can be called with init_view as its argument that returns a fiftyone.core.collections.SampleCollection defining an initial view from which to derive certain types of selection views. See selection_mode() for details

Attributes:

selection_mode

The current selection mode of the plot.

init_view

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

selected_ids

A list of IDs of the currently selected points.

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.

Methods:

recommend_link_type([label_field, samples])

Recommends a link type for the given info.

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.

register_disconnect_callback(callback)

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

select_ids(ids[, view])

Selects the points with the given IDs in this plot.

connect()

Connects this plot, if necessary.

disconnect()

Disconnects the plot, if necessary.

freeze()

Freezes the plot, replacing it with a static image.

save(path, **kwargs)

Saves the plot.

show(**kwargs)

Shows the plot.

reset()

Resets the plot to its default state.
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 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 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.

Recommends a link type for the given info.

Parameters:
Returns:

a (link_type, label_fields, selection_mode, init_fcn) tuple

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

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

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

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.

save(path, **kwargs)#

Saves the plot.

Parameters:

  • path – the path to write the plot

  • **kwargs – subclass-specific keyword arguments

show(**kwargs)#

Shows the plot.

The plot will be connected if necessary.

Parameters:

**kwargs – subclass-specific keyword arguments

property supports_session_updates#

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

reset()#

Resets the plot to its default state.