Replay and strategy
API reference for bar replay controls and the strategy tester tracker, report builder, and result types.
This page documents bar replay options and custom bar controls alongside the strategy tester APIs, including the strategy tracker, backtest report builder, and performance metric types.
Import symbols on this page from @luxalgo/vela-pro. Related guides: Bar replay, Strategy tester, Backtest results.
Feature enablers for this area (enableReplay, enableStrategyTester) are documented on Enablers and options.
Functions
buildStrategyReport
function buildStrategyReport(input: { title: string; state: StrategyState; trades: readonly StrategyTrade[] }): StrategyReportSee also: StrategyReport. From @luxalgo/vela/plugin: StrategyState, StrategyTrade.
replayResolutionControl
A replay-bar control (ReplayBarControl) choosing the replay resolution: Auto by default (candles appear whole, at the chart's timeframe) and a finer pick replays each candle through that timeframe's bars, one update per speed step (at 1x, a 15m candle from 1m updates takes 15 s).
function replayResolutionControl(opts?: ReplayResolutionControlOptions): ReplayBarControlSee also: ReplayBarControl, ReplayResolutionControlOptions.
timeframeMs
One chart bar's duration in ms for a timeframe string ('60', '1D', 'W', 'M', '30S'); null when unknown.
Also exported from @luxalgo/vela-pro/plugin.
function timeframeMs(tf: string): number | nullClasses
StrategyTesterPanel
The strategy tester: a summary strip (net profit, trades, win rate, drawdown, profit factor over the equity curve) that maximizes into the full report (Performance, Trades Analysis and Trades Log). It draws its own header in both.
class StrategyTesterPanel {
constructor(
ctx: WidgetContext,
tracker: StrategyTracker,
header: BottomPanelHeader,
openDock?: () => void,
);
readonly el: HTMLElement;
readonly isMobile: boolean;
setVisible(on: boolean): void;
destroy(): void;
}| Member | Type | Description |
|---|---|---|
constructor | (ctx: WidgetContext, tracker: StrategyTracker, header: BottomPanelHeader, openDock?: () => void) | openDock: Open the dock on this panel (the mobile Backtest button). Default: openDock = () => {}. |
el | HTMLElement | |
isMobile | boolean | The shell runs its mobile layout: the report opens from a button, never as a strip. |
setVisible() | (on: boolean) => void | |
destroy() | () => void |
See also: BottomPanelHeader, StrategyTracker. From @luxalgo/vela/plugin: WidgetContext.
StrategyTracker
class StrategyTracker {
constructor(ctx: WidgetContext);
onFirstRun: ((s: TrackedStrategy) => void) | null;
readonly selected: TrackedStrategy | null;
list(): TrackedStrategy[];
select(id: string): void;
onChange(cb: () => void): () => void;
destroy(): void;
}| Member | Type | Description |
|---|---|---|
constructor | (ctx: WidgetContext) | |
onFirstRun | ((s: TrackedStrategy) => void) | null | Called the first time a strategy shows up on the active chart. |
selected | TrackedStrategy | null | |
list() | () => TrackedStrategy[] | |
select() | (id: string) => void | |
onChange() | (cb: () => void) => () => void | |
destroy() | () => void |
See also: TrackedStrategy. From @luxalgo/vela/plugin: WidgetContext.
Interfaces and types
EquityPoint
interface EquityPoint {
time: number;
equity: number;
drawdown: number;
trade?: number;
side?: 'long' | 'short';
}| Member | Type | Description |
|---|---|---|
time | number | |
equity | number | Closed-trade net profit so far. |
drawdown | number | Distance below the running peak (≤ 0). |
trade? | number | The closed trade this point follows (ReportTrade.index); absent on the starting point. |
side? | 'long' | 'short' |
ReplayBarControl
A dropdown the host adds to the replay control bar, right after the speed selector: e.g. the timeframe whose bars replay each candle (chart.replay.setTicks; replayResolutionControl is the ready-made one).
interface ReplayBarControl {
id: string;
title?: string;
options: readonly ReplayBarOption[] | ((ctx: { chart: WidgetContext['chart'] }) => readonly ReplayBarOption[]);
value?: string;
tooltip?: string;
onChange(value: string, ctx: { chart: WidgetContext['chart'] }): void;
}| Member | Type | Description |
|---|---|---|
id | string | |
title? | string | Heading shown at the top of the open list (the bar itself shows the selection). |
options | readonly ReplayBarOption[] | ((ctx: { chart: WidgetContext['chart'] }) => readonly ReplayBarOption[]) | The entries, or a function of the chart, re-read whenever a replay starts (the chart's market may have changed since). |
value? | string | The default selection (default: the first option): also where the bar falls back when a re-read no longer lists the user's pick. |
tooltip? | string | Hover text on the dropdown. |
onChange() | (value: string, ctx: { chart: WidgetContext['chart'] }) => void | Runs on every pick, and again with the current value whenever the bar binds a chart (a shell may replace its instance), so the control's effect always lands on the live one. |
See also: ReplayBarOption. From @luxalgo/vela/plugin: WidgetContext.
ReplayBarOption
One entry of a ReplayBarControl.
interface ReplayBarOption {
value: string;
label: string;
selected?: string;
}| Member | Type | Description |
|---|---|---|
value | string | |
label | string | The entry in the open list. |
selected? | string | What the bar shows once this entry is picked (default: label). |
ReplayPickShade
How the start pick veils the chart right of the pick line.
interface ReplayPickShade {
color?: string;
opacity?: number;
}| Member | Type | Description |
|---|---|---|
color? | string | Default: the chart background. |
opacity? | number | 0..1: default 0.6. |
ReplayResolutionControlOptions
Options for replayResolutionControl.
interface ReplayResolutionControlOptions {
timeframes?: readonly string[];
title?: string;
tooltip?: string;
}| Member | Type | Description |
|---|---|---|
timeframes? | readonly string[] | Candidate finer timeframes; each is offered when it evenly divides the chart's. |
title? | string | The list heading (default 'Replay Resolution'). |
tooltip? | string | The dropdown's hover text. |
ReportTrade
interface ReportTrade {
index: number;
id: string;
side: 'long' | 'short';
qty: number;
entryId: string;
entryTime: number;
entryPrice: number;
exitId: string | null;
exitTime: number | null;
exitPrice: number | null;
open: boolean;
pnl: number | null;
pnlPct: number | null;
cumulative: number | null;
runup: number | null;
drawdown: number | null;
commission: number | null;
}SideMetrics
interface SideMetrics {
netProfit: number;
netProfitPct: number | null;
grossProfit: number;
grossLoss: number;
profitFactor: number | null;
commission: number;
trades: number;
wins: number;
losses: number;
even: number;
winRate: number | null;
avgTrade: number | null;
avgTradePct: number | null;
avgWin: number | null;
avgLoss: number | null;
winLossRatio: number | null;
largestWin: number | null;
largestLoss: number | null;
largestWinPct: number | null;
largestLossPct: number | null;
avgDurationMs: number | null;
avgWinDurationMs: number | null;
avgLossDurationMs: number | null;
maxConsecutiveWins: number;
maxConsecutiveLosses: number;
avgPerDay: number | null;
avgPerWeek: number | null;
cagr: number | null;
longestMs: number | null;
shortestMs: number | null;
tradesPerDay: number | null;
tradesPerWeek: number | null;
}| Member | Type | Description |
|---|---|---|
netProfit | number | |
netProfitPct | number | null | |
grossProfit | number | |
grossLoss | number | |
profitFactor | number | null | |
commission | number | |
trades | number | |
wins | number | |
losses | number | |
even | number | |
winRate | number | null | |
avgTrade | number | null | |
avgTradePct | number | null | |
avgWin | number | null | |
avgLoss | number | null | |
winLossRatio | number | null | |
largestWin | number | null | |
largestLoss | number | null | |
largestWinPct | number | null | |
largestLossPct | number | null | |
avgDurationMs | number | null | |
avgWinDurationMs | number | null | |
avgLossDurationMs | number | null | |
maxConsecutiveWins | number | |
maxConsecutiveLosses | number | |
avgPerDay | number | null | Net profit per calendar day / week the closed trades span. |
avgPerWeek | number | null | |
cagr | number | null | Compound annual growth of this side's net profit over its span. |
longestMs | number | null | |
shortestMs | number | null | |
tradesPerDay | number | null | |
tradesPerWeek | number | null |
StrategyReport
interface StrategyReport {
title: string;
initialCapital: number;
position: { qty: number; avgPrice: number; openPnl: number };
finalEquity: number;
netPnl: number;
engine?: {
sharpe?: number;
sortino?: number;
buyHoldPnl?: number;
buyHoldPct?: number;
outperformance?: number;
};
maxDrawdown: number;
maxDrawdownPct: number | null;
maxRunup: number;
all: SideMetrics;
long: SideMetrics;
short: SideMetrics;
sharpe: number | null;
sortino: number | null;
cagr: number | null;
equity: EquityPoint[];
trades: ReportTrade[];
distribution: Array<{ from: number; to: number; count: number; tone: 'profit' | 'loss' }>;
daily: Array<{ day: number; pnl: number; trades: number; wins: number }>;
weekday: number[];
weekdayTrades: number[];
calmar: number | null;
firstTime: number | null;
lastTime: number | null;
}| Member | Type | Description |
|---|---|---|
title | string | |
initialCapital | number | |
position | { qty: number; avgPrice: number; openPnl: number } | The open position at the last bar. |
finalEquity | number | |
netPnl | number | The engine's own net profit (commissions included even when the ledger lacks them). |
engine? | { sharpe?: number; sortino?: number; buyHoldPnl?: number; buyHoldPct?: number; outperformance?: number; } | Figures only the engine can give (they need every bar): absent when it reports none. |
maxDrawdown | number | |
maxDrawdownPct | number | null | |
maxRunup | number | |
all | SideMetrics | |
long | SideMetrics | |
short | SideMetrics | |
sharpe | number | null | Calendar-month returns of the closed-trade equity, annualized. |
sortino | number | null | |
cagr | number | null | Compound annual growth over the first entry → last exit span. |
equity | EquityPoint[] | |
trades | ReportTrade[] | |
distribution | Array<{ from: number; to: number; count: number; tone: 'profit' | 'loss' }> | Closed trades by P&L %, in buckets. |
daily | Array<{ day: number; pnl: number; trades: number; wins: number }> | Net P&L, closed trades and winners by the UTC day trades closed on. |
weekday | number[] | Net P&L by weekday of the exit, Monday first. |
weekdayTrades | number[] | Closed trades by weekday of the exit, Monday first. |
calmar | number | null | Return over the largest drawdown (annual growth % / max drawdown %). |
firstTime | number | null | |
lastTime | number | null |
See also: EquityPoint, ReportTrade, SideMetrics.
TrackedStrategy
interface TrackedStrategy {
id: string;
title: string;
report: StrategyReport | null;
}See also: StrategyReport.
Constants
REPLAY_ACTION_ID
The topbar action's id.
const REPLAY_ACTION_ID: 'vela-pro.replay';STRATEGY_PANEL_ID
const STRATEGY_PANEL_ID: 'vela-pro.strategy';