Plot declarations and export¶

View Markdown

self.plotting describes strategy visuals: lines, histograms, levels, fills, markers, and bar colors. The package exports their data; it does not open or render an interactive chart. Use the exported payload with your own renderer.

Plotting · export_result · PaneRef · PlotRef · FillRef · MarkerRef · PlottingLimits · PlottingError

Declare and export visuals¶

from openbacktesting import Backtest, Strategy, colors
from openbacktesting.plotting import export_result
from openbacktesting.test import GOOG

class VisualStrategy(Strategy):
    def init(self):
        self.average = self.ta.ema(length=20)
        self.rsi = self.ta.rsi(length=14)
        self.plotting.line(self.average, title="EMA 20", color=colors.BLUE)
        pane = self.plotting.pane("momentum", title="Momentum")
        self.plotting.line(self.rsi, title="RSI", pane=pane, color=colors.PURPLE)
        self.plotting.level(70, pane=pane, color=colors.GRAY)

    def next(self):
        if self.average.valid[-1] and self.close[-1] > self.average[-1]:
            self.plotting.bar_color(colors.GREEN)

result = Backtest(GOOG, VisualStrategy).run()
payload = export_result(result)
print(len(payload["plots"]))

Select a drawing method¶

Method	Arguments and returned value
`pane(id=None, title=None)`	Create a separate pane in `init()`; returns `PaneRef`. Omit `pane` elsewhere for the main price pane.
`line(source, ...)`	Single-channel indicator/data handle; returns `PlotRef`. `style="line"` or `"step"`.
`histogram(source, baseline=0, ...)`	Bars measured from the baseline; returns `PlotRef`.
`level(value, ...)`	Finite scalar horizontal level; returns `PlotRef`.
`fill(lower, upper, ...)`	Two compatible line/level references in the same pane; returns `FillRef`.
`marker(..., position="above_bar")`	Mark an event in `next()`; returns `MarkerRef`. Use `below_bar` or `price` with a finite `price` for other positions.
`bg_color(color, pane=None)`	Current-bar background, in `next()`; returns `None`.
`bar_color(color)`	Current price candle color, in `next()`; returns `None`.

Create panes and static plots in init(). Sources must be same-run single-channel handles, not arrays or callbacks. Common arguments are id (optional unique identifier), title (display label), pane, and color (Color or six/eight-digit hex). References belong to one run and cannot be reused across backtests.

gap_policy="break" leaves gaps at missing values; "connect" connects valid observations. offset_bars is a nonnegative visual shift, not a change to calculation timing. A marker's shape is circle, square, triangle_up, or triangle_down; text adds a label. anchor_bar can associate a confirmed event with an earlier bar, without making it known earlier.

For fills, retain the returned lines, for example lower = self.plotting.line(self.bands.lower) and upper = self.plotting.line(self.bands.upper), then self.plotting.fill(lower, upper, color=colors.BLUE.with_transparency(85)).

Colors and limits¶

Colors accept Color, "#RRGGBB", or "#RRGGBBAA"; see Color. bg_color(None) and bar_color(None) clear the current override. The last call for that bar/target wins; colors do not carry into the next bar unless you write them again.

Backtest(..., plotting=False) disables historical visual collection. PlottingLimits adjusts positive budgets for panes, plots, points, events, text, and exported bytes; exceeding one raises PlottingError. Use error.code to identify issues such as invalid-phase, invalid-reference, or PlottingLimitExceeded.

The export is a plain dictionary with market data, sources, drawing declarations, and actual execution facts. Write it with json.dump(payload, file, allow_nan=False) if you need a file; export itself has no file or browser side effects. Markers represent strategy calls, while fills represent actual executions, which can occur on different bars.

Plotting¶

Access through Strategy.plotting; init declares market-data/indicator layers, and next/on_order/on_fill add markers.

Plotting.fill¶

Plotting.fill(lower, upper, id=None, title=None, color=None, gap_policy='break')

Fill between two layers; endpoints must share pane, axis, offset, and compatible units.

Plotting.histogram¶

Plotting.histogram(
    source,
    id=None,
    title=None,
    pane=None,
    color=None,
    baseline=0,
    gap_policy='break',
    offset_bars=0,
)

Declare a histogram; a finite baseline contributes to consumer vertical-axis autoscaling.

Plotting.level¶

Plotting.level(value, id=None, title=None, pane=None, color=None)

Declare a finite horizontal line, storing one constant rather than duplicating a full array.

Plotting.line¶

Plotting.line(
    source,
    id=None,
    title=None,
    pane=None,
    color=None,
    style='line',
    gap_policy='break',
    offset_bars=0,
)

Declare a line or step line, defaulting to the main chart with broken gaps; offsets affect display only.

Plotting.marker¶

Plotting.marker(
    id=None,
    title=None,
    pane=None,
    *,
    position='above_bar',
    price=None,
    shape='circle',
    text='',
    color=None,
    anchor_bar=None,
)

Record a runtime marker; anchor_bar may refer to historical bars, while knownAtBar is always the current bar.

Plotting.pane¶

Plotting.pane(id=None, title=None)

Create a separate pane in init; return a reference for subsequent layers to share an automatically scaled vertical axis.

Plotting.bg_color¶

Plotting.bg_color(color, *, pane=None)

Write the current bar's pane background only in next; the last write to the same target wins.

Plotting.bar_color¶

Plotting.bar_color(color)

Color the current main-chart candle only in next, applying one override to body, wick, and border.

export_result¶

plotting.export_result(result)

Return an independent PlottingResult dictionary from a successful backtest's frozen snapshot without reading the strategy instance.

Returned drawing references¶

Use a PaneRef as a pane argument, and PlotRef values as fill boundaries. .id and .title identify a drawing. FillRef and MarkerRef identify completed declarations; do not construct reference objects yourself.

PaneRef¶

Separate-pane identity for the current run; pass this reference only to pane arguments.

Attribute	Type	Meaning
`id`	`str`	Read-only identity of the drawing in this run.
`title`	`str`	Display title of the drawing.

PlotRef¶

Line, histogram, or horizontal-line identity usable as a fill endpoint.

Attribute	Type	Meaning
`id`	`str`	Read-only identity of the drawing in this run.
`title`	`str`	Display title of the drawing.

FillRef¶

Fill identity between two compatible layers.

Attribute	Type	Meaning
`id`	`str`	Read-only identity of the drawing in this run.
`title`	`str`	Display title of the drawing.

MarkerRef¶

Identity of one runtime marker.

Attribute	Type	Meaning
`id`	`str`	Read-only identity of the drawing in this run.
`title`	`str`	Display title of the drawing.

PlottingLimits¶

plotting.PlottingLimits(
    panes=32,
    plots=256,
    points=10000000,
    events=1000000,
    text=1048576,
    bytes=268435456,
)

Collection budgets; all limits are positive integers, and bytes is checked during explicit export.

Attribute	Type	Meaning
`panes`	`int`	Maximum panes, including the main pane.
`plots`	`int`	Maximum plots, including fills.
`points`	`int`	Maximum retained numeric/mask points.
`events`	`int`	Maximum color, marker, fill, and account events.
`text`	`int`	Maximum UTF-8 bytes of labels and other text.
`bytes`	`int`	Maximum compact JSON export bytes.

PlottingError¶

Plotting contract error; code is a stable category for caller dispatch.

code — Stable error category; see the plotting guide for details.

Colors · Indicators · User manual