API reference

lapbox.plot

Plotly figures for lapbox’s results: the optional plot extra.

Install with pip install "lapbox[plot]". Nothing else in lapbox imports Plotly; without it, import lapbox.plot raises an ImportError that says what to install.

Every function returns a plotly.graph_objects.Figure: call .show(), .write_html(path), or .write_image(path) (with kaleido). The figures keep the library’s caveats: a lap’s frozen car data is shaded, a pair that couldn’t be matched is drawn without anything that compares the laps point by point (and says why), and minisectors decided by less than 20 ms are grey.

Summary

channel_traces: One lap’s channels against distance, one row each; frozen car data shaded grey.
comparison: Two laps from compare: the time gap on top, then both drivers’ channels on the shared distance axis. Also available as Comparison.plot.
speed_delta: Driver A’s speed minus driver B’s against distance (above zero, A is faster there).
track_dominance: Driver A’s racing line coloured by who took less time through each minisector.

Figures

channel_tracesfunction

from lapbox.plot import channel_traces

channel_traces(tel, *, channels=None, driver='', title=None)

One lap’s channels against distance, one row each; frozen car data shaded grey.

Parameters

tel: pd.DataFrame: One lap’s telemetry.
channels: list[str] | None = None: Channels to draw, top to bottom; defaults to those present of Speed, Throttle, Brake, RPM, nGear, DRS.
driver: str = '': Shown in the default title.
title: str | None = None: Replaces the default title.

Returns

plotly.graph_objects.Figure

Raises

ValueError: no Distance column, or no channel to draw.

comparisonfunction

from lapbox.plot import comparison

comparison(result, *, channels=None, title=None)

Two laps from compare: the time gap on top, then both drivers’ channels on the shared distance axis. Also available as Comparison.plot.

Parameters

result: Comparison: From compare.
channels: list[str] | None = None: Channels to draw; defaults to those the aligned frame has.
title: str | None = None: Replaces the default “A vs B”.

Returns

plotly.graph_objects.Figure

Raises

ValueError: the aligned frame has no channel to draw.

Above zero on the gap row, driver A is ahead at that point. When result.matched is False the gap row is left out and the title gives the reason: the residual, and each lap’s longest frozen stretch. Each lap’s own trace is still drawn.

speed_deltafunction

from lapbox.plot import speed_delta

speed_delta(result)

Driver A’s speed minus driver B’s against distance (above zero, A is faster there).

Parameters

result: Comparison: From compare.

Returns

plotly.graph_objects.Figure; for an unmatched pair, an empty figure that says why.

Raises

ValueError: the aligned frame has no speed for both drivers.

track_dominancefunction

from lapbox.plot import track_dominance

track_dominance(result, tel_a, *, tie_margin=0.02)

Driver A’s racing line coloured by who took less time through each minisector.

Parameters

result: Comparison: From compare.
tel_a: pd.DataFrame: Driver A’s lap, with X, Y and Distance (the comparison’s axis is A’s).
tie_margin: float = 0.02: Minisectors decided by less than this many seconds are grey: too close to call.

Returns

plotly.graph_objects.Figure; for an unmatched pair, an empty figure that says why.

Raises

ValueError: tel_a has no X, Y or Distance.

These docs describe lapbox 0.1.0. Something wrong or missing? Open an issue.