> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.conductorquantum.com/api-reference/stanza-api/plotter/backends/utils/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.conductorquantum.com/_mcp/server.

# stanza.plotter.backends.utils

Shared utilities for plotting backends.

This module centralizes small, reusable helpers used by multiple
plotting backends to keep implementations minimal and consistent.

## Module Contents

### Classes

| Name | Description |
|------|-------------|
| [`PlotSpec`](#stanzaplotterbackendsutilsplotspec) | Plot specification with type-safe fields. |
| [`PlotState`](#stanzaplotterbackendsutilsplotstate) | Complete plot state: source, figure, and spec in one place. |

### Functions

| Name | Description |
|------|-------------|
| [`prepare_heatmap_data`](#stanzaplotterbackendsutilsprepare_heatmap_data) | Calculate rect sizes and update color range for heatmap data. |
| [`make_line_plot`](#stanzaplotterbackendsutilsmake_line_plot) | Create a 1D line plot. |
| [`make_heatmap_plot`](#stanzaplotterbackendsutilsmake_heatmap_plot) | Create a 2D heatmap plot. |

### Data

`LINE_PLOT_WIDTH`
`LINE_PLOT_HEIGHT`
`HEATMAP_WIDTH`
`HEATMAP_HEIGHT`

### API

```python
stanza.plotter.backends.utils.LINE_PLOT_WIDTH
```

**Value**: `800`


```python
stanza.plotter.backends.utils.LINE_PLOT_HEIGHT
```

**Value**: `400`


```python
stanza.plotter.backends.utils.HEATMAP_WIDTH
```

**Value**: `800`


```python
stanza.plotter.backends.utils.HEATMAP_HEIGHT
```

**Value**: `600`


```python
class stanza.plotter.backends.utils.PlotSpec
```

Plot specification with type-safe fields.

```python
name: str
```

**Value**: `None`


```python
plot_type: str
```

**Value**: `None`


```python
x_label: str
```

**Value**: `None`


```python
y_label: str
```

**Value**: `None`


```python
z_label: str | None
```

**Value**: `None`


```python
cell_size: tuple[float, float] | None
```

**Value**: `None`


```python
mapper: bokeh.models.LinearColorMapper | None
```

**Value**: `None`


```python
dx: float | None
```

**Value**: `None`


```python
dy: float | None
```

**Value**: `None`


```python
value_min: float
```

**Value**: `float(...)`


```python
value_max: float
```

**Value**: `float(...)`


```python
class stanza.plotter.backends.utils.PlotState
```

Complete plot state: source, figure, and spec in one place.

Single source of truth for a plot's data, visualization, and configuration.
Ownership is clear: whoever has the PlotState owns the entire plot.

```python
source: bokeh.models.ColumnDataSource
```

**Value**: `None`


```python
figure: typing.Any
```

**Value**: `None`


```python
spec: stanza.plotter.backends.utils.PlotSpec
```

**Value**: `None`


```python
stanza.plotter.backends.utils.prepare_heatmap_data(
    data: dict[str, typing.Any],
    existing_data: dict[str, typing.Any],
    spec: stanza.plotter.backends.utils.PlotSpec
) -> dict[str, typing.Any]
```

Calculate rect sizes and update color range for heatmap data.

**Parameters:**

<ParamField path="data" type="dict[str, typing.Any]">
  New data to add (x, y, value)
</ParamField>

<ParamField path="existing_data" type="dict[str, typing.Any]">
  Existing data in the data source
</ParamField>

<ParamField path="spec" type="stanza.plotter.backends.utils.PlotSpec">
  Plot specification with dx, dy, value_min, value_max
</ParamField>

**Returns:**

Updated data with width and height fields added


```python
stanza.plotter.backends.utils.make_line_plot(
    name: str,
    x_label: str,
    y_label: str
) -> stanza.plotter.backends.utils.PlotState
```

Create a 1D line plot.

Returns complete PlotState with source, figure, and spec.


```python
stanza.plotter.backends.utils.make_heatmap_plot(
    name: str,
    x_label: str,
    y_label: str,
    z_label: str | None,
    cell_size: tuple[float, float] | None
) -> stanza.plotter.backends.utils.PlotState
```

Create a 2D heatmap plot.

Returns complete PlotState with source, figure, and spec.