`charts`#

Build your own plots for reports and the analysis panel.

Create data series and combine them into a figure:

Series: charts.Scatter (lines/points), charts.Bar, charts.Heatmap, charts.Contour.
Container: charts.Figure — add series to it and set its title/axes.
Styling: charts.Line, charts.Marker, charts.Font, charts.Axis, charts.Shape, charts.Annotation.

Example

fig = charts.Figure()
fig.add(charts.Scatter(x=xs, y=ys, mode="lines+markers"))
fig.update_layout(title="My plot", xaxis=charts.Axis(title="x"))
viz.show_figure(fig)  # or reporting.add_figure("plot", fig)

Annotation #

Annotation(
    x: float | str | None = None,
    y: float | str | None = None,
    text: str | None = None,
    showarrow: bool | None = None,
    textangle: float | None = None,
    xanchor: Literal["auto", "left", "center", "right"]
    | None = None,
    yanchor: Literal["auto", "top", "middle", "bottom"]
    | None = None,
    font: Font | dict[str, Any] | None = None,
    xref: str | None = None,
    yref: str | None = None,
    ax: float | None = None,
    ay: float | None = None,
    arrowcolor: str | None = None,
    arrowwidth: float | None = None,
    bgcolor: str | None = None,
    extras: dict[str, Any] = ...,
) -> None

A text annotation placed at a point on the plot, optionally with an arrow.

Axis #

Axis(
    title: str | dict[str, Any] | None = None,
    range: list[float] | tuple[float, float] | None = None,
    autorange: bool | Literal["reversed"] | None = None,
    type: Literal["linear", "log", "date", "category"]
    | None = None,
    showgrid: bool | None = None,
    gridcolor: str | None = None,
    gridwidth: float | None = None,
    zeroline: bool | None = None,
    zerolinecolor: str | None = None,
    zerolinewidth: float | None = None,
    tickformat: str | None = None,
    showticklabels: bool | None = None,
    domain: list[float] | tuple[float, float] | None = None,
    anchor: str | None = None,
    matches: str | None = None,
    nticks: int | None = None,
    extras: dict[str, Any] = ...,
) -> None

Settings for one axis: title, range, scale, gridlines, and ticks.

Common fields: title, range=[lo, hi] (or autorange=True), type="log" for a logarithmic scale, and showgrid.

Bar #

Bar(
    x: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    y: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    name: str | None = None,
    marker: Marker | dict[str, Any] | None = None,
    orientation: Literal["v", "h"] | None = None,
    xaxis: str | None = None,
    yaxis: str | None = None,
    showlegend: bool | None = None,
    visible: bool | None = None,
    type: Literal["bar"] = "bar",
    extras: dict[str, Any] = ...,
) -> None

A bar series — vertical bars by default, horizontal with orientation="h".

Contour #

Contour(
    z: Sequence[Sequence[float]]
    | Sequence[Sequence[int]]
    | ndarray
    | None = None,
    x: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    y: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    colorscale: str
    | list[tuple[float, str]]
    | list[list[Any]]
    | None = None,
    contours: dict[str, Any] | None = None,
    line: Line | dict[str, Any] | None = None,
    ncontours: int | None = None,
    showcolorbar: bool | None = None,
    name: str | None = None,
    xaxis: str | None = None,
    yaxis: str | None = None,
    visible: bool | None = None,
    type: Literal["contour"] = "contour",
    extras: dict[str, Any] = ...,
) -> None

Contour lines over a 2D grid of values (a topographic-style map).

Like Heatmap, but draws lines joining equal values. ncontours sets roughly how many levels to draw.

Figure #

Figure(
    data: list[
        Scatter | Heatmap | Contour | Bar | dict[str, Any]
    ] = ...,
    layout: Layout = ...,
) -> None

A complete plot: one or more data series plus a Layout.

Add series with add, draw extra marks with add_shape / add_annotation, and set titles and axes with update_layout. All of these return the figure, so calls can be chained. Pass the finished figure to viz.show_figure(...) or reporting.add_figure(...).

Font #

Font(
    size: float | None = None,
    color: str | float | None = None,
    family: str | None = None,
    extras: dict[str, Any] = ...,
) -> None

Font styling for titles, axis labels, and annotation text.

Heatmap #

Heatmap(
    z: Sequence[Sequence[float]]
    | Sequence[Sequence[int]]
    | ndarray
    | None = None,
    x: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    y: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    colorscale: str
    | list[tuple[float, str]]
    | list[list[Any]]
    | None = None,
    showcolorbar: bool | None = None,
    name: str | None = None,
    xaxis: str | None = None,
    yaxis: str | None = None,
    visible: bool | None = None,
    type: Literal["heatmap"] = "heatmap",
    extras: dict[str, Any] = ...,
) -> None

A 2D grid of values shown as colours.

z is the grid (rows × columns); optional x and y label the column and row positions. colorscale sets the colour mapping.

Layout #

Layout(
    title: str | dict[str, Any] | None = None,
    xaxis: Axis | dict[str, Any] | None = None,
    yaxis: Axis | dict[str, Any] | None = None,
    xaxis2: Axis | dict[str, Any] | None = None,
    xaxis3: Axis | dict[str, Any] | None = None,
    xaxis4: Axis | dict[str, Any] | None = None,
    yaxis2: Axis | dict[str, Any] | None = None,
    yaxis3: Axis | dict[str, Any] | None = None,
    yaxis4: Axis | dict[str, Any] | None = None,
    showlegend: bool | None = None,
    legend: dict[str, Any] | None = None,
    margin: Margin | dict[str, Any] | None = None,
    shapes: list[Shape | dict[str, Any]] = ...,
    annotations: list[Annotation | dict[str, Any]] = ...,
    paper_bgcolor: str | None = None,
    plot_bgcolor: str | None = None,
    height: float | None = None,
    width: float | None = None,
    font: Font | dict[str, Any] | None = None,
    hovermode: Literal[
        "x", "y", "closest", "x unified", "y unified", False
    ]
    | None = None,
    extras: dict[str, Any] = ...,
) -> None

The figure's overall look: title, axes, legend, margins, shapes, annotations.

Usually set through Figure.update_layout rather than constructed directly. xaxis2/yaxis2 (and …3/…4) support extra axes for multi-panel figures.

Line #

Line(
    color: str | None = None,
    width: float | None = None,
    dash: Literal[
        "solid",
        "dot",
        "dash",
        "longdash",
        "dashdot",
        "longdashdot",
    ]
    | None = None,
    extras: dict[str, Any] = ...,
) -> None

Line styling: color, width, and dash pattern.

Marker #

Marker(
    color: str | list[str] | list[float] | None = None,
    size: float | list[float] | None = None,
    symbol: Literal[
        "circle",
        "square",
        "diamond",
        "cross",
        "x",
        "triangle-up",
        "triangle-down",
    ]
    | None = None,
    line: Line | dict[str, Any] | None = None,
    extras: dict[str, Any] = ...,
) -> None

Marker styling for data points (color, size, symbol).

Scatter #

Scatter(
    x: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    y: Sequence[float]
    | Sequence[int]
    | Sequence[str]
    | ndarray
    | None = None,
    mode: Literal[
        "lines",
        "markers",
        "lines+markers",
        "text",
        "lines+markers+text",
    ]
    | None = None,
    name: str | None = None,
    line: Line | dict[str, Any] | None = None,
    marker: Marker | dict[str, Any] | None = None,
    fill: Literal[
        "none",
        "tozeroy",
        "tozerox",
        "tonexty",
        "tonextx",
        "toself",
    ]
    | None = None,
    fillcolor: str | None = None,
    xaxis: str | None = None,
    yaxis: str | None = None,
    text: list[str] | str | None = None,
    textfont: Font | dict[str, Any] | None = None,
    textposition: Literal[
        "top left",
        "top center",
        "top right",
        "middle left",
        "middle center",
        "middle right",
        "bottom left",
        "bottom center",
        "bottom right",
    ]
    | None = None,
    showlegend: bool | None = None,
    visible: bool | None = None,
    type: Literal["scatter"] = "scatter",
    extras: dict[str, Any] = ...,
) -> None

A line and/or point series — the most common plot type.

Set mode to "lines", "markers", or "lines+markers" to choose between a connected line, scattered points, or both. Style with line= and marker=.

Shape #

Shape(
    type: Literal[
        "line", "rect", "circle", "path", "triangle"
    ]
    | None = None,
    x0: float | str | None = None,
    x1: float | str | None = None,
    y0: float | str | None = None,
    y1: float | str | None = None,
    path: str | None = None,
    xref: str | None = None,
    yref: str | None = None,
    line: Line | dict[str, Any] | None = None,
    fillcolor: str | None = None,
    opacity: float | None = None,
    layer: Literal["above", "below"] | None = None,
    tipX: float | None = None,
    tipY: float | None = None,
    dx: float | None = None,
    dy: float | None = None,
    lengthPx: float | None = None,
    widthPx: float | None = None,
    label: str | None = None,
    labelColor: str | None = None,
    labelFontSize: float | None = None,
    extras: dict[str, Any] = ...,
) -> None

A shape drawn over the plot to highlight a region or point.

Set type to "line", "rect", "circle", or "path" and give its corners with x0/y0/x1/y1. A "triangle" type is also available as a peak marker (positioned with tipX/tipY and sized with the dx/ dy/lengthPx/widthPx/label fields).

charts#