Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo

Replay and strategy

API reference for bar replay controls and the strategy tester tracker, report builder, and result types.

View as Markdown

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[] }): StrategyReport

See 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): ReplayBarControl

See 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 | null

Classes

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;
}
MemberTypeDescription
constructor(ctx: WidgetContext, tracker: StrategyTracker, header: BottomPanelHeader, openDock?: () => void)openDock: Open the dock on this panel (the mobile Backtest button). Default: openDock = () => {}.
elHTMLElement
isMobilebooleanThe 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;
}
MemberTypeDescription
constructor(ctx: WidgetContext)
onFirstRun((s: TrackedStrategy) => void) | nullCalled the first time a strategy shows up on the active chart.
selectedTrackedStrategy | 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';
}
MemberTypeDescription
timenumber
equitynumberClosed-trade net profit so far.
drawdownnumberDistance below the running peak (≤ 0).
trade?numberThe 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;
}
MemberTypeDescription
idstring
title?stringHeading shown at the top of the open list (the bar itself shows the selection).
optionsreadonly 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?stringThe default selection (default: the first option): also where the bar falls back when a re-read no longer lists the user's pick.
tooltip?stringHover text on the dropdown.
onChange()(value: string, ctx: { chart: WidgetContext['chart'] }) => voidRuns 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;
}
MemberTypeDescription
valuestring
labelstringThe entry in the open list.
selected?stringWhat 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;
}
MemberTypeDescription
color?stringDefault: the chart background.
opacity?number0..1: default 0.6.

ReplayResolutionControlOptions

Options for replayResolutionControl.

interface ReplayResolutionControlOptions {
    timeframes?: readonly string[];
    title?: string;
    tooltip?: string;
}
MemberTypeDescription
timeframes?readonly string[]Candidate finer timeframes; each is offered when it evenly divides the chart's.
title?stringThe list heading (default 'Replay Resolution').
tooltip?stringThe 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;
}
MemberTypeDescription
netProfitnumber
netProfitPctnumber | null
grossProfitnumber
grossLossnumber
profitFactornumber | null
commissionnumber
tradesnumber
winsnumber
lossesnumber
evennumber
winRatenumber | null
avgTradenumber | null
avgTradePctnumber | null
avgWinnumber | null
avgLossnumber | null
winLossRationumber | null
largestWinnumber | null
largestLossnumber | null
largestWinPctnumber | null
largestLossPctnumber | null
avgDurationMsnumber | null
avgWinDurationMsnumber | null
avgLossDurationMsnumber | null
maxConsecutiveWinsnumber
maxConsecutiveLossesnumber
avgPerDaynumber | nullNet profit per calendar day / week the closed trades span.
avgPerWeeknumber | null
cagrnumber | nullCompound annual growth of this side's net profit over its span.
longestMsnumber | null
shortestMsnumber | null
tradesPerDaynumber | null
tradesPerWeeknumber | 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;
}
MemberTypeDescription
titlestring
initialCapitalnumber
position{ qty: number; avgPrice: number; openPnl: number }The open position at the last bar.
finalEquitynumber
netPnlnumberThe 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.
maxDrawdownnumber
maxDrawdownPctnumber | null
maxRunupnumber
allSideMetrics
longSideMetrics
shortSideMetrics
sharpenumber | nullCalendar-month returns of the closed-trade equity, annualized.
sortinonumber | null
cagrnumber | nullCompound annual growth over the first entry → last exit span.
equityEquityPoint[]
tradesReportTrade[]
distributionArray<{ from: number; to: number; count: number; tone: 'profit' | 'loss' }>Closed trades by P&L %, in buckets.
dailyArray<{ day: number; pnl: number; trades: number; wins: number }>Net P&L, closed trades and winners by the UTC day trades closed on.
weekdaynumber[]Net P&L by weekday of the exit, Monday first.
weekdayTradesnumber[]Closed trades by weekday of the exit, Monday first.
calmarnumber | nullReturn over the largest drawdown (annual growth % / max drawdown %).
firstTimenumber | null
lastTimenumber | 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';

On this page