Visualization¶

To plot straight from a pipeline result, the one-liner plot_result (or result.plot) names a concept and wires up the prepare function and context for you; available_concepts(result) lists what a given result can render:

from ob_analytics import Pipeline, sample_csv_path
from ob_analytics.visualization import plot_result

result = Pipeline().run(sample_csv_path())

fig = plot_result(result, "depth_heatmap")          # drawn at L2 only
fig = result.plot("trade_tape", "L3", backend="plotly")

For full control, the unified plot() dispatcher renders a concept at a resolution level on a chosen backend from already-prepared data. Prepare the payload with the matching helper in the public prepare namespace (friendly wrappers over the internal prepare-data functions) and spread it as keyword arguments:

from ob_analytics.visualization import plot, prepare

fig = plot("trade_tape", level="L2", **prepare.trades(result.trades))

backend="matplotlib" (default) returns a Matplotlib figure; backend="plotly" returns an interactive Plotly figure (requires pip install ob-analytics[interactive]); backend="bokeh" returns a Bokeh figure (requires pip install ob-analytics[bokeh]), covering the core concepts — trade_tape, depth_heatmap, book_snapshot, depth_chart — for Bokeh / Panel server dashboards and streaming views. Renderers never call plt.show().

Every concept declares a resolution level — Level.L2 (Market-By-Price aggregate) or Level.L3 (Market-By-Order, per order). A concept registered at a single level resolves it automatically, so you pass only the concept name; comparable concepts (both L2 and L3 registered) take an explicit level=.

Concepts with both L2 and L3 faces: trade_tape, order_activity, cancellations, book_snapshot, depth_chart, book_replay, liquidity_at_touch. L2-only: time_series, depth_heatmap, volume_percentiles, events_histogram, hidden_executions, price_view, trade_size. L3-only: order_outcome, queue_position. Level-less analytics: vpin, order_flow_imbalance, kyle_lambda, ofi_horizon, l1_ticker, book_signals, transaction_costs, amihud, roll_spread, bars, trading_halts. All but the last two are also registered metrics, so result.plot("vpin") computes and draws them.

Book replay¶

book_replay steps through the book over part of a run. The ladder shows the book at one instant per interval. Beside it, the trades panel shows every trade of the replay and the mid, with a line at the time on screen. Drag the slider, or press a play button: Play 1× is real time, and each speed in speeds gets a button. A speed is smooth only when a frame lasts about 50 ms or less, so at 1 s per frame, Play 20× glides and the slower speeds step. For smoother slow playback, pass a shorter interval. The file grows with the number of frames, which max_frames caps at 600. When interval would need more frames, the replay uses a longer interval and logs a warning.

result.plot() and the gallery replay the gallery's zoom window: the busiest stretch of trading (busiest_window), half as long as a run shorter than two hours, or a quarter as long as a longer run. They set interval to 1 s, or longer so that the window fits in about 300 frames. On the sample data the window is about 15 minutes, so each frame is about 3 s and every speed steps. To choose the window and the interval yourself, pass start_time, end_time and interval:

import pandas as pd

start = result.trades["timestamp"].iloc[100]
fig = result.plot(
    "book_replay", "L2", backend="plotly",
    start_time=start, end_time=start + pd.Timedelta("5min"), interval="1s",
)

Click a trade to move the replay to the last frame at or before it. The price level the trade took is marked in the trade's colour: the ask for a buy, the bid for a sell.

The L2 face replays the depth table, so its touch equals the depth summary's at every frame. The L3 face rebuilds the per-order book from the events at each frame, with stale crossed orders removed (uncross=True, the default here) so that both faces show the same market. Pass uncross=False for the faithful L3 book. Every frame keeps one price range: the mid's path, wide enough for about price_levels price levels per side. A crossed frame has no mid, so it adds its best bid and best ask to the path instead.

from ob_analytics.visualization import plot_result

fig = plot_result(result, "book_replay", "L3", backend="plotly")
fig.write_html("replay.html")

The replay is drawn by Plotly only, and the concept table says so: asking another backend for it raises a KeyError that names Plotly. The clicking needs a script, which Plotly cannot store inside a figure, so the replay is a BookReplayFigure: a Plotly figure that adds the script whenever it becomes HTML (write_html, to_html, show, and display in a notebook). In a notebook it displays as HTML, so the notebook must be trusted for the clicking to work.

book_replay(
    depth: DataFrame | None = None,
    trades: DataFrame | None = None,
    events: DataFrame | None = None,
    per_order: bool = False,
    start_time: Timestamp | None = None,
    end_time: Timestamp | None = None,
    interval: str | timedelta = "1s",
    max_frames: int = 600,
    price_levels: int = 20,
    speeds: tuple[float, ...] = (1, 5, 20),
    volume_scale: float | None = None,
    uncross: bool = True,
) -> dict[str, Any]

Dispatcher¶

plot(
    concept: str,
    level: Level | str | None = _UNSET,
    *,
    backend: str = "matplotlib",
    ax: Axes | None = None,
    **data: Any,
) -> Any

from ob_analytics.visualization import plot
from ob_analytics.visualization import _data
fig = plot("trade_tape", backend="matplotlib",
           **_data.prepare_trades_data(trades))

Theme and Saving¶

Pass theme=PlotTheme(...) to plot() to override DEFAULT_THEME for a single call, on any backend; there is no global theme to set.

PlotTheme(
    style: str = "white",
    context: str = "notebook",
    font_scale: float = 1.05,
    palette: Palette = DEFAULT_PALETTE,
    rc: dict[str, object] = (
        lambda: {
            "axes.grid": True,
            "grid.linestyle": ":",
            "grid.alpha": 0.35,
            "axes.spines.top": False,
            "axes.spines.right": False,
            "axes.edgecolor": DEFAULT_PALETTE.rule,
            "axes.titlelocation": "left",
            "axes.titleweight": "bold",
            "lines.linewidth": 2.0,
        }
    )(),
    plotly_layout: dict[str, object] = (
        lambda: {
            "title": {
                "x": 0.0,
                "xanchor": "left",
                "xref": "paper",
                "font": {"weight": "bold"},
            }
        }
    )(),
    bokeh_figure: dict[str, object] = dict(),
)

dark: bool

text_scale: float

DEFAULT_THEME: PlotTheme = PlotTheme()

Palette(
    bid: str = "#0072B2",
    ask: str = "#D55E00",
    buy: str = "#009E73",
    sell: str = "#D55E00",
    filled: str = "#009E73",
    partial: str = "#CC79A7",
    cancelled: str = "#E69F00",
    hidden_trade: str = "#F0E442",
    price_line: str = "#222222",
    reference_line: str = "#888888",
    rule: str = "#444444",
    label: str = "#555555",
    spread_fill: str = "#9aa0a6",
    neutral: str = "#7f8c8d",
    series: str = "#5dade2",
    emphasis: str = "#e74c3c",
    threshold: str = "#f39c12",
    secondary_axis: str = "#f1c40f",
    imbalance: str = "#6d28d9",
    effective_spread: str = "#0072B2",
    realized_spread: str = "#CC79A7",
)

Palette(bid="#1f77b4", ask="#d62728")

DEFAULT_PALETTE: Palette = Palette()

save_figure(
    fig: Figure,
    path: str | Path,
    *,
    dpi: int = 150,
    **kwargs: object,
) -> None

infer_volume_scale = infer_volume_scale

Display windows¶

The gallery picks one time window and one price band per run, and every face it clips gets the same bounds. Pass them to your own faces to match it.

busiest_window = busiest_window

focus_window = focus_window

FocusWindow = FocusWindow

Renderer registry¶

Every plot of the package is declared once, in a concept table, at the coordinate (concept, level, backend) (where level is a Level or None for level-less analytics). The table says which backends draw each plot, and the built-in backends register their renderers into RENDERERS from it. Asking a backend for a plot it does not draw raises UnknownNameError (also a KeyError) that names the backends that do. A concept is level-less or drawn at a level, and the same kind on every backend: registering it the other way raises ConfigError. Register a whole new backend module with register_plot_backend (or advertise it under the ob_analytics.plot_backends entry-point group), or a single renderer directly with RENDERERS.register((concept, level, backend), fn); plot(), plot_result() and the gallery find such a renderer as they find the table's. To see how a concept is registered before adding to it, list its (level, backend) pairs with RENDERERS.placements(concept).

register_plot_backend(name: str, module_path: str) -> None

>>> from ob_analytics.visualization import register_plot_backend
>>> register_plot_backend("bokeh", "my_pkg._bokeh")

load_plot_backend_plugins(
    *, force: bool = False
) -> list[str]

RENDERERS: RendererRegistry = RendererRegistry('renderer')

RendererRegistry(kind: str)

get(key: RendererKey) -> RendererFn

missing(
    concept: str, level: Level | None, backend: str
) -> UnknownNameError

placements(
    concept: str,
) -> tuple[tuple[Level | None, str], ...]

register(key: RendererKey, value: RendererFn) -> None