module documentation

Plotly plots.

Copyright 2017-2025, Voxel51, Inc.

Class InteractiveHeatmap An interactive Plotly heatmap.
Class InteractiveScatter Wrapper class that turns a Plotly figure containing one or more scatter-type traces into an fiftyone.core.plots.base.InteractivePlot.
Class PlotlyInteractivePlot Base class for fiftyone.core.plots.base.InteractivePlot instances with Plotly backends.
Class PlotlyNotebookPlot A wrapper around a Plotly plot for Jupyter notebook contexts that allows it to be replaced with a screenshot by calling freeze.
Class PlotlyWidgetMixin Mixin for Plotly plots that use widgets to display in Jupyter notebooks.
Function get_colormap Generates a continuous colormap with the specified number of colors from the given plotly colorscale.
Function lines Plots the given lines(s) data.
Function location_scatterplot Generates an interactive scatterplot of the given location coordinates with a map rendered in the background of the plot.
Function plot_confusion_matrix Plots a confusion matrix.
Function plot_pr_curve Plots a precision-recall (PR) curve.
Function plot_pr_curves Plots a set of per-class precision-recall (PR) curves.
Function plot_regressions Plots the given regression results.
Function plot_roc_curve Plots a receiver operating characteristic (ROC) curve.
Function scatterplot Generates an interactive scatterplot of the given points.
Variable logger Undocumented
Function _check_plotly_jupyter_environment Undocumented
Function _compute_zoom_center Undocumented
Function _get_colorscale Undocumented
Function _get_continuous_color Undocumented
Function _get_qualitative_colors Undocumented
Function _get_qualitative_colorscale Undocumented
Function _make_edges_scatter Undocumented
Function _make_edges_scatter_mapbox Undocumented
Function _parse_titles Undocumented
Function _patch_perform_plotly_relayout Attempts to patch an unresolved issue with zooming/panning FigureWidgets with Mapbox plots.
Function _plot_confusion_matrix_interactive Undocumented
Function _plot_confusion_matrix_static Undocumented
Function _plot_scatter_categorical Undocumented
Function _plot_scatter_categorical_single_trace Undocumented
Function _plot_scatter_mapbox_categorical Undocumented
Function _plot_scatter_mapbox_categorical_single_trace Undocumented
Function _plot_scatter_mapbox_density Undocumented
Function _plot_scatter_mapbox_numeric Undocumented
Function _plot_scatter_numeric Undocumented
Function _set_map_type_to_figure Undocumented
Function _to_log_colorscale Undocumented
Constant _DEFAULT_CONTINUOUS_COLORSCALE Undocumented
Constant _DEFAULT_LAYOUT Undocumented
Constant _DEFAULT_LINE_COLOR Undocumented
Constant _MAX_LABEL_TRACES Undocumented
def get_colormap(colorscale, n=256, hex_strs=False): (source)

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
colorscalea valid colorscale. See above for possible options
n:256the desired number of colors
hex_strs:Falsewhether 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
def 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): (source)

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:Nonethe fiftyone.core.collections.SampleCollection whose data is being visualized
ids:Nonean 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:Nonea name or list of names for the line traces
colors:Nonea list of colors to use for the line traces. See https://plotly.com/python/colorscales for options
marker_size:Nonethe marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points
figure:Nonea plotly:plotly.graph_objects.Figure to which to add the plot
title:Nonea title for the plot
xaxis_title:Nonean x-axis title
yaxis_title:Nonea y-axis title
sizes_title:Nonea 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:Falsewhether to set the axes to equal scale
**kwargsoptional keyword arguments for plotly:plotly.graph_objects.Figure.update_layout
Returns

one of the following

def 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): (source)

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:Nonethe fiftyone.core.collections.SampleCollection whose data is being visualized
ids:Nonean 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:Nonea 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:Nonea 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:Nonethe plot style to use. Only applicable when the color data is numeric. Supported values are ("scatter", "density")
radius:Nonethe 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:Nonea plotly:plotly.graph_objects.Figure to which to add the plot
multi_trace:Nonewhether 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:Nonethe marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points
colorscale:Nonea plotly colorscale to use. Only applicable when labels contains numeric data. See https://plotly.com/python/colorscales for options
log_colorscale:Falsewhether 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:Nonea title for the plot
trace_title:Nonea name for the scatter trace. Only applicable when plotting a single trace
labels_title:Nonea 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:Nonea 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:Nonea title string to use for edges in the legend. If none is provided, edges are not included in the legend
show_colorbar_title:Nonewhether 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")
**kwargsoptional keyword arguments for plotly:plotly.graph_objects.Figure.update_layout
Returns

one of the following

def 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): (source)

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_matrixa num_true x num_preds confusion matrix
labelsa max(num_true, num_preds) array-like of class labels
ids:Nonean array-like of same shape as confusion_matrix whose elements are array-likes of label IDs corresponding to each cell
samples:Nonethe 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:Nonethe evaluation key of the evaluation
gt_field:Nonethe name of the ground truth field
pred_field:Nonethe name of the predictions field
colorscale:"oranges"a plotly colorscale to use. See https://plotly.com/python/colorscales for options
log_colorscale:Falsewhether 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:Nonea title for the plot
**kwargsoptional keyword arguments for plotly:plotly.graph_objects.Figure.update_layout
Returns

one of the following

def plot_pr_curve(precision, recall, thresholds=None, label=None, style='area', figure=None, title=None, **kwargs): (source)

Plots a precision-recall (PR) curve.

Parameters
precisionan array-like of precision values
recallan array-like of recall values
thresholds:Nonean array-like of decision thresholds
label:Nonea label for the curve
style:"area"a plot style to use. Supported values are ("area", "line")
figure:Nonea plotly:plotly.graph_objects.Figure to which to add the plot
title:Nonea title for the plot
**kwargsoptional keyword arguments for plotly: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
def plot_pr_curves(precisions, recall, classes, thresholds=None, figure=None, title=None, **kwargs): (source)

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

Parameters
precisionsa num_classes x num_recalls array-like of per-class precision values
recallan array-like of recall values
classesthe list of classes
thresholds:Nonea num_classes x num_recalls array-like of decision thresholds
figure:Nonea plotly:plotly.graph_objects.Figure to which to add the plots
title:Nonea title for the plot
**kwargsoptional keyword arguments for plotly: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
def 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): (source)

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
ytruean array-like of ground truth values
ypredan array-like of predicted values
samples:Nonethe fiftyone.core.collections.SampleCollection for which the results were generated. Only used by the "plotly" backend when IDs are provided
ids:Nonean 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:Nonea 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:Nonethe name of the ground truth field
pred_field:Nonethe name of the predictions field
figure:Nonea plotly:plotly.graph_objects.Figure to which to add the plot
best_fit_label:Nonea custom legend label for the best fit line
marker_size:Nonethe marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points
title:Nonea title for the plot
labels_title:Nonea 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:Nonea 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:Nonewhether 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
**kwargsoptional keyword arguments for plotly:plotly.graph_objects.Figure.update_layout
Returns

one of the following

def plot_roc_curve(fpr, tpr, thresholds=None, roc_auc=None, style='area', figure=None, title=None, **kwargs): (source)

Plots a receiver operating characteristic (ROC) curve.

Parameters
fpran array-like of false positive rates
tpran array-like of true positive rates
thresholds:Nonean array-like of decision thresholds
roc_auc:Nonethe area under the ROC curve
style:"area"a plot style to use. Supported values are ("area", "line")
figure:Nonea plotly:plotly.graph_objects.Figure to which to add the plot
title:Nonea title for the plot
**kwargsoptional keyword arguments for plotly: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
def 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): (source)

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
pointsa num_points x num_dims array-like of points
samples:Nonethe fiftyone.core.collections.SampleCollection whose data is being visualized
ids:Nonean 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:Nonea 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:Nonea 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:Nonea plotly:plotly.graph_objects.Figure to which to add the plot
multi_trace:Nonewhether 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:Nonethe marker size to use. If sizes are provided, this value is used as a reference to scale the sizes of all points
colorscale:Nonea plotly colorscale to use. Only applicable when labels contains numeric data. See https://plotly.com/python/colorscales for options
log_colorscale:Falsewhether 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:Nonea title for the plot
trace_title:Nonea name for the scatter trace. Only applicable when plotting a single trace
labels_title:Nonea 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:Nonea 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:Nonea title string to use for edges in the legend. If none is provided, edges are not included in the legend
show_colorbar_title:Nonewhether 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:Falsewhether to set the axes to equal scale
**kwargsoptional keyword arguments for plotly: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

Undocumented

def _check_plotly_jupyter_environment(): (source)

Undocumented

def _compute_zoom_center(coords, pad=0.2, aspect_ratio=2.0): (source)

Undocumented

def _get_colorscale(name): (source)

Undocumented

def _get_continuous_color(colorscale, value): (source)

Undocumented

def _get_qualitative_colors(num_classes, colors=None): (source)

Undocumented

def _get_qualitative_colorscale(num_classes, colors=None): (source)

Undocumented

def _make_edges_scatter(points, edges, edges_title): (source)

Undocumented

def _make_edges_scatter_mapbox(coords, edges, edges_title): (source)

Undocumented

def _parse_titles(labels, labels_title, sizes, sizes_title, show_colorbar_title): (source)

Undocumented

def _patch_perform_plotly_relayout(): (source)

Attempts to patch an unresolved issue with zooming/panning FigureWidgets with Mapbox plots.

https://github.com/plotly/plotly.py/issues/2570

def _plot_confusion_matrix_interactive(confusion_matrix, labels, ids, samples=None, eval_key=None, gt_field=None, pred_field=None, colorscale=None, title=None, **kwargs): (source)

Undocumented

def _plot_confusion_matrix_static(confusion_matrix, labels, colorscale=None, title=None, gt_field=None, pred_field=None, **kwargs): (source)

Undocumented

def _plot_scatter_categorical(points, labels, classes, sizes, edges, ids, figure, marker_size, labels_title, sizes_title, edges_title, colorbar_title, axis_equal, colors=None): (source)

Undocumented

def _plot_scatter_categorical_single_trace(points, labels, classes, sizes, edges, ids, figure, marker_size, trace_title, labels_title, sizes_title, edges_title, colorbar_title, axis_equal, colors=None): (source)

Undocumented

def _plot_scatter_mapbox_categorical(coords, labels, classes, sizes, edges, ids, figure, marker_size, labels_title, sizes_title, edges_title, colorbar_title, colors=None): (source)

Undocumented

def _plot_scatter_mapbox_categorical_single_trace(coords, labels, classes, sizes, edges, ids, figure, marker_size, trace_title, labels_title, sizes_title, edges_title, colorbar_title, colors=None): (source)

Undocumented

def _plot_scatter_mapbox_density(coords, values, sizes, ids, figure, radius, colorscale, log_colorscale, trace_title, labels_title, sizes_title, colorbar_title): (source)

Undocumented

def _plot_scatter_mapbox_numeric(coords, values, sizes, edges, ids, figure, marker_size, colorscale, log_colorscale, trace_title, labels_title, sizes_title, edges_title, colorbar_title): (source)

Undocumented

def _plot_scatter_numeric(points, values, sizes, edges, ids, figure, marker_size, colorscale, log_colorscale, trace_title, labels_title, sizes_title, edges_title, colorbar_title, axis_equal): (source)

Undocumented

def _set_map_type_to_figure(figure, map_type): (source)

Undocumented

def _to_log_colorscale(colorscale, maxval): (source)

Undocumented

_DEFAULT_CONTINUOUS_COLORSCALE: str = (source)

Undocumented

Value
'viridis'
_DEFAULT_LAYOUT = (source)

Undocumented

Value
dict(template='ggplot2', margin={'r': 0, 't': 30, 'l': 0, 'b': 0})
_DEFAULT_LINE_COLOR: str = (source)

Undocumented

Value
'#FF6D04'
_MAX_LABEL_TRACES: int = (source)

Undocumented

Value
25