<!-- # hard line break macro for HTML -->

# fiftyone.core.plots.views

Plotly-powered view plots.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Classes:**

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

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

Bases: [`PlotlyWidgetMixin`](fiftyone.core.plots.plotly.md#fiftyone.core.plots.plotly.PlotlyWidgetMixin), [`ViewPlot`](fiftyone.core.plots.base.md#fiftyone.core.plots.base.ViewPlot)

Base class for `ViewPlot` instances with Plotly backends.

* **Parameters:**
  * **widget** – a [`plotly.graph_objects.FigureWidget`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.FigureWidget)
  * **init_view** (*None*) – an optional initial
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to load

**Methods:**

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

**Attributes:**

| [`is_connected`](#fiftyone.core.plots.views.PlotlyViewPlot.is_connected)                         | Whether this plot is currently connected.                                    |
|--------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`is_disconnected`](#fiftyone.core.plots.views.PlotlyViewPlot.is_disconnected)                   | Whether this plot is currently disconnected.                                 |
| [`is_frozen`](#fiftyone.core.plots.views.PlotlyViewPlot.is_frozen)                               | Whether this plot is currently frozen.                                       |
| [`link_type`](#fiftyone.core.plots.views.PlotlyViewPlot.link_type)                               | The link type between this plot and a connected session.                     |
| [`supports_session_updates`](#fiftyone.core.plots.views.PlotlyViewPlot.supports_session_updates) | Whether this plot supports automatic updates in response to session changes. |

#### show(\*\*kwargs)

Shows this plot.

* **Parameters:**
  **\*\*kwargs** – optional parameters for
  [`plotly.graph_objects.Figure.update_layout()`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.Figure.update_layout)

#### connect()

Connects this plot, if necessary.

#### disconnect()

Disconnects the plot, if necessary.

#### freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

#### *property* is_connected

Whether this plot is currently connected.

#### *property* is_disconnected

Whether this plot is currently disconnected.

#### *property* is_frozen

Whether this plot is currently frozen.

#### *property* link_type

The link type between this plot and a connected session.

#### reset()

Resets the plot to its default state.

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

Saves the plot as an image or HTML.

* **Parameters:**
  * **path** – the path to write the image or HTML
  * **width** (*None*) – a desired width in pixels when saving as an image.
    By default, the layout width is used
  * **height** (*None*) – a desired height in pixels when saving as an image.
    By default, the layout height is used
  * **scale** (*None*) – a scale factor to apply to the layout dimensions. By
    default, this is 1.0
  * **\*\*kwargs** – keyword arguments for
    `plotly:plotly.graph_objects.Figure.to_image()` or
    `plotly:plotly.graph_objects.Figure.write_html()`

#### *property* supports_session_updates

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

#### update_view(view, agg_results=None)

Updates the plot based on the provided view.

* **Parameters:**
  * **view** – a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
  * **agg_results** (*None*) – a list of pre-computed aggregation results

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

Bases: [`PlotlyViewPlot`](#fiftyone.core.plots.views.PlotlyViewPlot)

A grid of [`PlotlyViewPlot`](#fiftyone.core.plots.views.PlotlyViewPlot) instances.

* **Parameters:**
  * **plots** – a [`PlotlyViewPlot`](#fiftyone.core.plots.views.PlotlyViewPlot) or iterable of [`PlotlyViewPlot`](#fiftyone.core.plots.views.PlotlyViewPlot)
    instances
  * **shape** (*None*) – the `(rows, cols)` shape to use for the grid
  * **hgap** (*None*) – a horizontal spacing between the subplots, in `[0, 1]`
  * **vgap** (*None*) – a vertical spacing between the subplots, in `[0, 1]`
  * **init_view** (*None*) – an optional initial
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to load
  * **\*\*kwargs** – optional parameters for
    [`plotly.graph_objects.Figure.update_layout()`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.Figure.update_layout)

**Methods:**

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

**Attributes:**

| [`is_connected`](#fiftyone.core.plots.views.ViewGrid.is_connected)                         | Whether this plot is currently connected.                                    |
|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`is_disconnected`](#fiftyone.core.plots.views.ViewGrid.is_disconnected)                   | Whether this plot is currently disconnected.                                 |
| [`is_frozen`](#fiftyone.core.plots.views.ViewGrid.is_frozen)                               | Whether this plot is currently frozen.                                       |
| [`link_type`](#fiftyone.core.plots.views.ViewGrid.link_type)                               | The link type between this plot and a connected session.                     |
| [`supports_session_updates`](#fiftyone.core.plots.views.ViewGrid.supports_session_updates) | Whether this plot supports automatic updates in response to session changes. |

#### connect()

Connects this plot, if necessary.

#### disconnect()

Disconnects the plot, if necessary.

#### freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

#### *property* is_connected

Whether this plot is currently connected.

#### *property* is_disconnected

Whether this plot is currently disconnected.

#### *property* is_frozen

Whether this plot is currently frozen.

#### *property* link_type

The link type between this plot and a connected session.

#### reset()

Resets the plot to its default state.

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

Saves the plot as an image or HTML.

* **Parameters:**
  * **path** – the path to write the image or HTML
  * **width** (*None*) – a desired width in pixels when saving as an image.
    By default, the layout width is used
  * **height** (*None*) – a desired height in pixels when saving as an image.
    By default, the layout height is used
  * **scale** (*None*) – a scale factor to apply to the layout dimensions. By
    default, this is 1.0
  * **\*\*kwargs** – keyword arguments for
    `plotly:plotly.graph_objects.Figure.to_image()` or
    `plotly:plotly.graph_objects.Figure.write_html()`

#### show(\*\*kwargs)

Shows this plot.

* **Parameters:**
  **\*\*kwargs** – optional parameters for
  [`plotly.graph_objects.Figure.update_layout()`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.Figure.update_layout)

#### *property* supports_session_updates

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

#### update_view(view, agg_results=None)

Updates the plot based on the provided view.

* **Parameters:**
  * **view** – a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
  * **agg_results** (*None*) – a list of pre-computed aggregation results

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

Bases: [`PlotlyViewPlot`](#fiftyone.core.plots.views.PlotlyViewPlot)

A histogram of a categorial field.

* **Parameters:**
  * **field_or_expr** – a field name, `embedded.field.name`,
    [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression), or
    [MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
    defining the field or expression to plot
  * **expr** (*None*) – 

    an optional
    [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
    [MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
    to apply to `field_or_expr` (which must be a field) before
    plotting
  * **order** ( *"alphabetical"*) – the x-axis ordering strategy to use. Can be
    “alphabetical” to sort by field value, or “frequency” to sort in
    descending order of frequency, or a function suitable for
    `sorted(items, key=order)`, where `items` is a list of
    `(value, count)` tuples
  * **xlabel** (*None*) – an optional x-label for the plot
  * **log** (*False*) – whether to use a log scale y-axis
  * **bargap** (*None*) – relative spacing between bars in `[0, 1]`
  * **color** (*None*) – a color for the bars. Can be any color supported by
    `plotly:plotly.graph_objects.bar.Marker.color()`
  * **opacity** (*None*) – an optional opacity for the bars in `[0, 1]`
  * **init_view** (*None*) – an optional initial
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to load
  * **\*\*kwargs** – optional parameters for
    [`plotly.graph_objects.Figure.update_layout()`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.Figure.update_layout)

**Methods:**

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

**Attributes:**

| [`is_connected`](#fiftyone.core.plots.views.CategoricalHistogram.is_connected)                         | Whether this plot is currently connected.                                    |
|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`is_disconnected`](#fiftyone.core.plots.views.CategoricalHistogram.is_disconnected)                   | Whether this plot is currently disconnected.                                 |
| [`is_frozen`](#fiftyone.core.plots.views.CategoricalHistogram.is_frozen)                               | Whether this plot is currently frozen.                                       |
| [`link_type`](#fiftyone.core.plots.views.CategoricalHistogram.link_type)                               | The link type between this plot and a connected session.                     |
| [`supports_session_updates`](#fiftyone.core.plots.views.CategoricalHistogram.supports_session_updates) | Whether this plot supports automatic updates in response to session changes. |

#### connect()

Connects this plot, if necessary.

#### disconnect()

Disconnects the plot, if necessary.

#### freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

#### *property* is_connected

Whether this plot is currently connected.

#### *property* is_disconnected

Whether this plot is currently disconnected.

#### *property* is_frozen

Whether this plot is currently frozen.

#### *property* link_type

The link type between this plot and a connected session.

#### reset()

Resets the plot to its default state.

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

Saves the plot as an image or HTML.

* **Parameters:**
  * **path** – the path to write the image or HTML
  * **width** (*None*) – a desired width in pixels when saving as an image.
    By default, the layout width is used
  * **height** (*None*) – a desired height in pixels when saving as an image.
    By default, the layout height is used
  * **scale** (*None*) – a scale factor to apply to the layout dimensions. By
    default, this is 1.0
  * **\*\*kwargs** – keyword arguments for
    `plotly:plotly.graph_objects.Figure.to_image()` or
    `plotly:plotly.graph_objects.Figure.write_html()`

#### show(\*\*kwargs)

Shows this plot.

* **Parameters:**
  **\*\*kwargs** – optional parameters for
  [`plotly.graph_objects.Figure.update_layout()`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.Figure.update_layout)

#### *property* supports_session_updates

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

#### update_view(view, agg_results=None)

Updates the plot based on the provided view.

* **Parameters:**
  * **view** – a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
  * **agg_results** (*None*) – a list of pre-computed aggregation results

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

Bases: [`PlotlyViewPlot`](#fiftyone.core.plots.views.PlotlyViewPlot)

A histogram of a numerical field.

* **Parameters:**
  * **field_or_expr** – 

    a field name, `embedded.field.name`,
    [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression), or
    [MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
    defining the field or expression to plot
  * **expr** (*None*) – 

    an optional
    [`fiftyone.core.expressions.ViewExpression`](fiftyone.core.expressions.md#fiftyone.core.expressions.ViewExpression) or
    [MongoDB expression](https://docs.mongodb.com/manual/meta/aggregation-quick-reference/#aggregation-expressions)
    to apply to `field_or_expr` (which must be a field) before
    plotting
  * **bins** (*None*) – can be either an integer number of bins to generate or a
    monotonically increasing sequence specifying the bin edges to use.
    By default, 10 bins are created. If `bins` is an integer and no
    `range` is specified, bin edges are automatically computed from
    the bounds of the field
  * **range** (*None*) – a `(lower, upper)` tuple specifying a range in which to
    generate equal-width bins. Only applicable when `bins` is an
    integer or `None`
  * **xlabel** (*None*) – an optional x-label for the plot
  * **log** (*False*) – whether to use a log scale y-axis
  * **color** (*None*) – a color for the bars. Can be any color supported by
    `plotly:plotly.graph_objects.bar.Marker.color()`
  * **opacity** (*None*) – an optional opacity for the bars in `[0, 1]`
  * **init_view** (*None*) – an optional initial
    [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) to load
  * **\*\*kwargs** – optional parameters for
    [`plotly.graph_objects.Figure.update_layout()`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.Figure.update_layout)

**Methods:**

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

**Attributes:**

| [`is_connected`](#fiftyone.core.plots.views.NumericalHistogram.is_connected)                         | Whether this plot is currently connected.                                    |
|------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`is_disconnected`](#fiftyone.core.plots.views.NumericalHistogram.is_disconnected)                   | Whether this plot is currently disconnected.                                 |
| [`is_frozen`](#fiftyone.core.plots.views.NumericalHistogram.is_frozen)                               | Whether this plot is currently frozen.                                       |
| [`link_type`](#fiftyone.core.plots.views.NumericalHistogram.link_type)                               | The link type between this plot and a connected session.                     |
| [`supports_session_updates`](#fiftyone.core.plots.views.NumericalHistogram.supports_session_updates) | Whether this plot supports automatic updates in response to session changes. |

#### connect()

Connects this plot, if necessary.

#### disconnect()

Disconnects the plot, if necessary.

#### freeze()

Freezes the plot, replacing it with a static image.

The plot will also be disconnected.

Only applicable in notebook contexts.

#### *property* is_connected

Whether this plot is currently connected.

#### *property* is_disconnected

Whether this plot is currently disconnected.

#### *property* is_frozen

Whether this plot is currently frozen.

#### *property* link_type

The link type between this plot and a connected session.

#### reset()

Resets the plot to its default state.

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

Saves the plot as an image or HTML.

* **Parameters:**
  * **path** – the path to write the image or HTML
  * **width** (*None*) – a desired width in pixels when saving as an image.
    By default, the layout width is used
  * **height** (*None*) – a desired height in pixels when saving as an image.
    By default, the layout height is used
  * **scale** (*None*) – a scale factor to apply to the layout dimensions. By
    default, this is 1.0
  * **\*\*kwargs** – keyword arguments for
    `plotly:plotly.graph_objects.Figure.to_image()` or
    `plotly:plotly.graph_objects.Figure.write_html()`

#### show(\*\*kwargs)

Shows this plot.

* **Parameters:**
  **\*\*kwargs** – optional parameters for
  [`plotly.graph_objects.Figure.update_layout()`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.html#plotly.graph_objects.Figure.update_layout)

#### *property* supports_session_updates

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

#### update_view(view, agg_results=None)

Updates the plot based on the provided view.

* **Parameters:**
  * **view** – a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection)
  * **agg_results** (*None*) – a list of pre-computed aggregation results