@tradecanvas/analytics

@tradecanvas/analytics

Backtesting, portfolio tracking, and risk analytics for TradeCanvas.

Preview release. API is stable but the engine has only been validated against synthetic test fixtures. Treat results as indicative until you've cross-checked them against your own reference implementation.

Install

npm install @tradecanvas/analytics @tradecanvas/commons

Backtester

Bar-by-bar engine. Strategy fn runs at close of each bar; orders fill on the next bar (market → next-bar open, limit/stop → when the next bar trades through the trigger price).

import { Backtester, FixedCommission, PercentSlippage } from '@tradecanvas/analytics'

const bt = new Backtester({
  initialCash: 10_000,
  commission: new FixedCommission(2),
  slippage: new PercentSlippage(0.0005),
  allowShort: true,
})

const result = bt.run(historicalBars, (ctx) => {
  if (!ctx.position) {
    ctx.placeOrder({ side: 'long', type: 'market', quantity: 1 })
  } else if (ctx.bar.close > ctx.position.averagePrice * 1.02) {
    ctx.close()
  }
})

console.log(result.metrics.sharpe, result.metrics.maxDrawdownPct)

StrategyContext

Field / method	Description
bar	Current bar
index	Index of bar in the input series
history	Bars up to and including bar
position	Current position or null
cash	Available cash
equity	Cash + mark-to-market position value
placeOrder(order)	Queue order for next bar
close(tag?)	Market-close current position
cancel(orderId)	Cancel a pending order

Commission & slippage models

• FixedCommission(perTrade)
• PercentCommission(rate) — fraction of notional, e.g. 0.001 = 10 bps
• PerShareCommission(perShare, minimum?)
• PercentSlippage(rate) — adverse fraction of price
• RangeBasedSlippage(factor) — proportional to bar range

Portfolio

Tracks cash, one net position, realized P&L, and the equity curve.

import { Portfolio } from '@tradecanvas/analytics'

const portfolio = new Portfolio({ initialCash: 10_000 })
portfolio.applyFill({ ... })
portfolio.mark(time, price)

portfolio.getPosition()        // → { side, quantity, averagePrice, ... } | null
portfolio.getTrades()          // → closed trades
portfolio.getEquityCurve()     // → equity points
portfolio.equity(price)        // mark-to-market

Currently single-position. Multi-symbol portfolios are on the roadmap.

Risk metrics

import { computeRiskMetrics } from '@tradecanvas/analytics'

const m = computeRiskMetrics(initialCash, equityCurve, trades, {
  periodsPerYear: 252,    // optional; auto-detected from timestamps
  riskFreeRate: 0.03,
})

m.totalReturnPct
m.cagr
m.sharpe
m.sortino
m.calmar
m.maxDrawdownPct
m.winRate
m.profitFactor
m.expectancy

Strategy library

Reference strategies live under @tradecanvas/analytics — drop in, tune parameters, run. All four implement the same StrategyFn shape and respect the backtester's allowShort flag.

import {
  Backtester,
  smaCrossStrategy,
  rsiReversionStrategy,
  donchianBreakoutStrategy,
  bollingerReversionStrategy,
} from '@tradecanvas/analytics';

const bt = new Backtester({ initialCash: 10_000 });

const result = bt.run(bars, smaCrossStrategy({
  fastPeriod: 10,
  slowPeriod: 30,
  size: 1,
}));

Strategy	Style	Tuning
smaCrossStrategy	Trend-following	fastPeriod, slowPeriod, size
rsiReversionStrategy	Mean-reversion (long-only)	period, oversold, overbought, size
donchianBreakoutStrategy	Trend breakout (Turtle-style)	entryPeriod, exitPeriod, size
bollingerReversionStrategy	Mean-reversion to SMA	period, stdDev, size

Each is a one-line function call returning a StrategyFn — easy to wrap, combine, or compare side-by-side in a backtest harness.

Edge cases (current behavior)

• Gaps past a limit price: if the bar opens already through the limit, the order fills at the better of open and the limit price.
• Stop orders inside a gap: fill at the worse of open and the stop price.
• Bar that touches both stop and limit on the same bar: order resolves to the more pessimistic price for the current side (no intra-bar tick simulation).

These choices are conservative. A future release will offer a configurable intra-bar fill model.

License

MIT