tradelab 0.4.0 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@
 
 ---
 
-**tradelab** handles the simulation, sizing, exits, costs, and result exports — you bring the candles and signal logic.
+**tradelab** handles the simulation, sizing, exits, costs, and result exports; you bring the data and signal logic.
 
 It works cleanly for a single-strategy backtest and scales up to portfolio runs, walk-forward testing, and detailed execution modeling. It is not a broker connector or a live trading tool.
 
@@ -31,6 +31,7 @@ npm install tradelab
 - [Core concepts](#core-concepts)
 - [Portfolio mode](#portfolio-mode)
 - [Walk-forward optimization](#walk-forward-optimization)
+- [Tick backtests](#tick-backtests)
 - [Execution and cost modeling](#execution-and-cost-modeling)
 - [Exports and reporting](#exports-and-reporting)
 - [CLI](#cli)
@@ -43,9 +44,9 @@ npm install tradelab
 
 | Area | What you get |
 |---|---|
-| **Engine** | Candle-based backtests with position sizing, exits, risk controls, replay capture |
-| **Portfolio** | Multi-symbol aggregation with weight-based capital allocation |
-| **Walk-forward** | Rolling train/test validation with parameter search |
+| **Engine** | Candle and tick backtests with position sizing, exits, replay capture, and cost models |
+| **Portfolio** | Multi-system shared-capital simulation with live capital locking and daily loss halts |
+| **Walk-forward** | Rolling and anchored train/test validation with parameter search and stability summaries |
 | **Data** | Yahoo Finance downloads, CSV import, and local cache helpers |
 | **Costs** | Slippage, spread, and commission modeling |
 | **Exports** | HTML reports, metrics JSON, and trade CSV |
@@ -177,19 +178,19 @@ The minimum viable signal is just `side`, `stop`, and `rr`. Start there and add
 {
   symbol, interval, range,
   trades,     // every realized leg, including partial exits
-  positions,  // completed positions — start here for analysis
+  positions,  // completed positions - start here for analysis
   metrics,    // winRate, profitFactor, maxDrawdown, sharpe, ...
-  eqSeries,   // [{ time, timestamp, equity }] — equity curve
+  eqSeries,   // [{ time, timestamp, equity }] - equity curve
   replay,     // visualization frames and events
 }
 ```
 
 **First checks after any run:**
 
-- `metrics.trades` — enough sample size to trust the numbers?
-- `metrics.profitFactor` — do winners beat losers gross of costs?
-- `metrics.maxDrawdown` — is the equity path survivable?
-- `metrics.sideBreakdown` — does one side carry the whole result?
+- `metrics.trades` - enough sample size to trust the numbers?
+- `metrics.profitFactor` - do winners beat losers gross of costs?
+- `metrics.maxDrawdown` - is the equity path survivable?
+- `metrics.sideBreakdown` - does one side carry the whole result?
 
 ---
 
@@ -209,19 +210,20 @@ const result = backtestPortfolio({
 });
 ```
 
-Capital is allocated up front by weight. Each system runs through the normal single-symbol engine, and the portfolio result merges trades, positions, replay events, and the equity series.
+Weights now act as default per-system allocation caps rather than pre-funded sleeves. Capital is locked only when a fill happens, `eqSeries` includes `lockedCapital` and `availableCapital`, later systems size against remaining live capital, and `maxDailyLossPct` on `backtestPortfolio()` can halt the whole book for the rest of the day.
 
 ---
 
 ## Walk-forward optimization
 
-Use `walkForwardOptimize()` when one in-sample backtest is not enough. It runs rolling train/test windows across the full candle history.
+Use `walkForwardOptimize()` when one in-sample backtest is not enough. It supports rolling and anchored train/test windows across the full candle history.
 
 ```js
 import { walkForwardOptimize } from "tradelab";
 
 const wf = walkForwardOptimize({
   candles,
+  mode: "anchored",
   trainBars: 180,
   testBars: 60,
   stepBars: 60,
@@ -236,7 +238,25 @@ const wf = walkForwardOptimize({
 });
 ```
 
-Each window picks the best parameter set in training, then runs it blind on the test slice. The `windows` array in the result shows per-window winners. If the winning parameters swing wildly from window to window, that is a real signal — not a formatting detail.
+Each window picks the best parameter set in training, then runs it blind on the test slice. The `windows` array now includes out-of-sample trade count, profitability, and a per-window stability score. `bestParamsSummary` reports how stable the winners were across the full run.
+
+---
+
+## Tick backtests
+
+Use `backtestTicks()` when you want event-driven fills on tick or quote data without changing the result shape used by metrics, exports, or replay.
+
+```js
+import { backtestTicks } from "tradelab";
+
+const result = backtestTicks({
+  ticks,
+  queueFillProbability: 0.35,
+  signal,
+});
+```
+
+Market entries fill on the next tick, limit orders can fill at the touch with configurable queue probability, and stop exits use the existing cost model with stop-specific slippage if you provide it in `costs.slippageByKind.stop`.
 
 ---
 
@@ -313,7 +333,7 @@ npx tradelab portfolio \
 # Walk-forward validation
 npx tradelab walk-forward \
   --source yahoo --symbol QQQ --interval 1d --period 2y \
-  --trainBars 180 --testBars 60
+  --trainBars 180 --testBars 60 --mode anchored
 
 # Prefetch and cache data
 npx tradelab prefetch --symbol SPY --interval 1d --period 1y
@@ -322,7 +342,7 @@ npx tradelab import-csv --csvPath ./data/spy.csv --symbol SPY --interval 1d
 
 **Built-in strategies:** `ema-cross` · `buy-hold`
 
-You can also point `--strategy` at a local module that exports `default(args)`, `createSignal(args)`, or `signal`.
+You can also point `--strategy` at a local module that exports `default(args)`, `createSignal(args)`, or `signal` for `backtest`, or `signalFactory(params, args)` plus `parameterSets`/`createParameterSets(args)` for `walk-forward`.
 
 ---
 
@@ -361,6 +381,7 @@ const { fetchHistorical } = require("tradelab/data");
 |---|---|
 | [Backtest engine](docs/backtest-engine.md) | Signal contract, all options, result shape, portfolio mode, walk-forward |
 | [Data, reporting, and CLI](docs/data-reporting-cli.md) | Data loading, cache behavior, exports, CLI reference |
+| [Strategy examples](docs/examples.md) | Mean reversion, breakout, sentiment, LLM, and portfolio strategy patterns |
 | [API reference](docs/api-reference.md) | Compact index of every public export |
 
 ---
@@ -368,7 +389,7 @@ const { fetchHistorical } = require("tradelab/data");
 ## Common mistakes
 
 - Using unsorted candles or mixed intervals in a single series
-- Reading `trades` as if they were always full positions — use `positions` for top-line analysis
+- Reading `trades` as if they were always full positions - use `positions` for top-line analysis
 - Leaving costs at zero and overestimating edge
 - Trusting one backtest without out-of-sample validation
 - Debugging a strategy with `strict: false` when lookahead is possible
@@ -380,4 +401,4 @@ const { fetchHistorical } = require("tradelab/data");
 - Node `18+` is required
 - Yahoo downloads are cached under `output/data` by default
 - CommonJS and ESM are both supported
-- The engine is built for historical research — not brokerage execution, tick-level simulation, or exchange microstructure modeling
+- The engine is built for historical research - not brokerage execution or full exchange microstructure simulation

package/bin/tradelab.js

@@ -48,6 +48,11 @@ function toList(value, fallback) {
     .filter((item) => Number.isFinite(item));
 }
 
+function parseJsonValue(value, fallback = null) {
+  if (!value) return fallback;
+  return JSON.parse(String(value));
+}
+
 function createEmaCrossSignal({
   fast = 10,
   slow = 30,
@@ -133,13 +138,70 @@ async function loadStrategy(strategyArg, args) {
   throw new Error(`Strategy module "${strategyArg}" must export default, createSignal, or signal`);
 }
 
+async function loadWalkForwardStrategy(strategyArg, args) {
+  if (!strategyArg || strategyArg === "ema-cross") {
+    const fasts = toList(args.fasts, [8, 10, 12]);
+    const slows = toList(args.slows, [20, 30, 40]);
+    const rrs = toList(args.rrs, [1.5, 2, 3]);
+    const parameterSets = [];
+
+    for (const fast of fasts) {
+      for (const slow of slows) {
+        if (fast >= slow) continue;
+        for (const rr of rrs) {
+          parameterSets.push({ fast, slow, rr });
+        }
+      }
+    }
+
+    return {
+      parameterSets,
+      signalFactory(params) {
+        return createEmaCrossSignal({
+          fast: params.fast,
+          slow: params.slow,
+          rr: params.rr,
+          stopLookback: toNumber(args.stopLookback, 15),
+        });
+      },
+    };
+  }
+
+  const resolved = path.resolve(process.cwd(), strategyArg);
+  const module = await import(pathToFileURL(resolved).href);
+  if (typeof module.signalFactory !== "function") {
+    throw new Error(
+      `Walk-forward strategy module "${strategyArg}" must export signalFactory`
+    );
+  }
+
+  const parameterSets =
+    parseJsonValue(args.parameterSets) ??
+    (typeof module.createParameterSets === "function"
+      ? await module.createParameterSets(args)
+      : module.parameterSets);
+
+  if (!Array.isArray(parameterSets) || parameterSets.length === 0) {
+    throw new Error(
+      `Walk-forward strategy module "${strategyArg}" must provide parameterSets, createParameterSets(args), or --parameterSets`
+    );
+  }
+
+  return {
+    parameterSets,
+    signalFactory(params) {
+      return module.signalFactory(params, args);
+    },
+  };
+}
+
 function printHelp() {
   console.log(`tradelab
 
 Commands:
   backtest      Run a one-off backtest from Yahoo or CSV data
   portfolio     Run multiple CSV datasets as an equal-weight portfolio
-  walk-forward  Run rolling train/test optimization with the built-in ema-cross strategy
+  walk-forward  Run rolling or anchored train/test optimization
   prefetch      Download Yahoo candles into the local cache
   import-csv    Normalize a CSV and save it into the local cache
 
@@ -257,26 +319,15 @@ async function commandWalkForward(args) {
     csvPath: args.csvPath,
     cache: args.cache !== "false",
   });
-  const fasts = toList(args.fasts, [8, 10, 12]);
-  const slows = toList(args.slows, [20, 30, 40]);
-  const rrs = toList(args.rrs, [1.5, 2, 3]);
-  const parameterSets = [];
-
-  for (const fast of fasts) {
-    for (const slow of slows) {
-      if (fast >= slow) continue;
-      for (const rr of rrs) {
-        parameterSets.push({ fast, slow, rr });
-      }
-    }
-  }
+  const walkForwardStrategy = await loadWalkForwardStrategy(args.strategy, args);
 
   const result = walkForwardOptimize({
     candles,
-    parameterSets,
+    parameterSets: walkForwardStrategy.parameterSets,
     trainBars: toNumber(args.trainBars, 120),
     testBars: toNumber(args.testBars, 40),
     stepBars: toNumber(args.stepBars, toNumber(args.testBars, 40)),
+    mode: args.mode || "rolling",
     scoreBy: args.scoreBy || "profitFactor",
     backtestOptions: {
       symbol: args.symbol || "DATA",
@@ -286,14 +337,7 @@ async function commandWalkForward(args) {
       riskPct: toNumber(args.riskPct, 1),
       warmupBars: toNumber(args.warmupBars, 20),
     },
-    signalFactory(params) {
-      return createEmaCrossSignal({
-        fast: params.fast,
-        slow: params.slow,
-        rr: params.rr,
-        stopLookback: toNumber(args.stopLookback, 15),
-      });
-    },
+    signalFactory: walkForwardStrategy.signalFactory,
   });
 
   const metricsPath = exportMetricsJSON({
@@ -310,6 +354,7 @@ async function commandWalkForward(args) {
         windows: result.windows.length,
         positions: result.positions.length,
         finalEquity: result.metrics.finalEquity,
+        bestParamsSummary: result.bestParamsSummary,
         metricsPath,
       },
       null,

package/dist/cjs/data.cjs

@@ -215,56 +215,87 @@ function buildMetrics({
   estBarMs,
   eqSeries
 }) {
-  const completedTrades = closed.filter((trade) => trade.exit.reason !== "SCALE");
-  const winningTrades = completedTrades.filter((trade) => trade.exit.pnl > 0);
-  const losingTrades = completedTrades.filter((trade) => trade.exit.pnl < 0);
-  const tradeRs = completedTrades.map(tradeRMultiple);
-  const totalR = sum(tradeRs);
-  const avgR = mean(tradeRs);
-  const labels = completedTrades.map(
-    (trade) => trade.exit.pnl > 0 ? "win" : trade.exit.pnl < 0 ? "loss" : "flat"
-  );
-  const { maxWin, maxLoss } = streaks(labels);
-  const tradePnls = completedTrades.map((trade) => trade.exit.pnl);
-  const expectancy = mean(tradePnls);
-  const tradeReturns = completedTrades.map(
-    (trade) => trade.exit.pnl / Math.max(1e-12, equityStart)
-  );
-  const tradeReturnStd = stddev(tradeReturns);
-  const sharpePerTrade = tradeReturnStd === 0 ? tradeReturns.length ? Infinity : 0 : mean(tradeReturns) / tradeReturnStd;
-  const sortinoPerTrade = sortino(tradeReturns);
-  const grossProfitPositions = sum(winningTrades.map((trade) => trade.exit.pnl));
-  const grossLossPositions = Math.abs(
-    sum(losingTrades.map((trade) => trade.exit.pnl))
-  );
-  const profitFactorPositions = grossLossPositions === 0 ? grossProfitPositions > 0 ? Infinity : 0 : grossProfitPositions / grossLossPositions;
   const legs = [...closed].sort((left, right) => left.exit.time - right.exit.time);
-  const winningLegs = legs.filter((trade) => trade.exit.pnl > 0);
-  const losingLegs = legs.filter((trade) => trade.exit.pnl < 0);
-  const grossProfitLegs = sum(winningLegs.map((trade) => trade.exit.pnl));
-  const grossLossLegs = Math.abs(sum(losingLegs.map((trade) => trade.exit.pnl)));
-  const profitFactorLegs = grossLossLegs === 0 ? grossProfitLegs > 0 ? Infinity : 0 : grossProfitLegs / grossLossLegs;
+  const completedTrades = [];
+  const tradeRs = [];
+  const tradePnls = [];
+  const tradeReturns = [];
+  const holdDurationsMinutes = [];
+  const labels = [];
+  const longRs = [];
+  const shortRs = [];
+  let totalR = 0;
+  let realizedPnL = 0;
+  let winningTradeCount = 0;
+  let grossProfitPositions = 0;
+  let grossLossPositions = 0;
+  let grossProfitLegs = 0;
+  let grossLossLegs = 0;
+  let winningLegCount = 0;
+  let openBars = 0;
+  let longTradesCount = 0;
+  let longTradeWins = 0;
+  let longPnLSum = 0;
+  let shortTradesCount = 0;
+  let shortTradeWins = 0;
+  let shortPnLSum = 0;
   let peakEquity = equityStart;
   let currentEquity = equityStart;
   let maxDrawdown = 0;
-  for (const leg of legs) {
-    currentEquity += leg.exit.pnl;
+  for (const trade of legs) {
+    const pnl = trade.exit.pnl;
+    realizedPnL += pnl;
+    if (pnl > 0) {
+      grossProfitLegs += pnl;
+      winningLegCount += 1;
+    } else if (pnl < 0) {
+      grossLossLegs += Math.abs(pnl);
+    }
+    currentEquity += pnl;
     if (currentEquity > peakEquity) peakEquity = currentEquity;
     const drawdown = (peakEquity - currentEquity) / Math.max(1e-12, peakEquity);
     if (drawdown > maxDrawdown) maxDrawdown = drawdown;
+    if (trade.exit.reason === "SCALE") continue;
+    completedTrades.push(trade);
+    tradePnls.push(pnl);
+    tradeReturns.push(pnl / Math.max(1e-12, equityStart));
+    const tradeR = tradeRMultiple(trade);
+    tradeRs.push(tradeR);
+    totalR += tradeR;
+    labels.push(pnl > 0 ? "win" : pnl < 0 ? "loss" : "flat");
+    const holdMinutes = (trade.exit.time - trade.openTime) / (1e3 * 60);
+    holdDurationsMinutes.push(holdMinutes);
+    openBars += Math.max(1, Math.round((trade.exit.time - trade.openTime) / estBarMs));
+    if (pnl > 0) {
+      winningTradeCount += 1;
+      grossProfitPositions += pnl;
+    } else if (pnl < 0) {
+      grossLossPositions += Math.abs(pnl);
+    }
+    if (trade.side === "long") {
+      longTradesCount += 1;
+      longPnLSum += pnl;
+      longRs.push(tradeR);
+      if (pnl > 0) longTradeWins += 1;
+    } else if (trade.side === "short") {
+      shortTradesCount += 1;
+      shortPnLSum += pnl;
+      shortRs.push(tradeR);
+      if (pnl > 0) shortTradeWins += 1;
+    }
   }
-  const realizedPnL = sum(closed.map((trade) => trade.exit.pnl));
+  const avgR = mean(tradeRs);
+  const { maxWin, maxLoss } = streaks(labels);
+  const expectancy = mean(tradePnls);
+  const tradeReturnStd = stddev(tradeReturns);
+  const sharpePerTrade = tradeReturnStd === 0 ? tradeReturns.length ? Infinity : 0 : mean(tradeReturns) / tradeReturnStd;
+  const sortinoPerTrade = sortino(tradeReturns);
+  const profitFactorPositions = grossLossPositions === 0 ? grossProfitPositions > 0 ? Infinity : 0 : grossProfitPositions / grossLossPositions;
+  const profitFactorLegs = grossLossLegs === 0 ? grossProfitLegs > 0 ? Infinity : 0 : grossProfitLegs / grossLossLegs;
   const returnPct = (equityFinal - equityStart) / Math.max(1e-12, equityStart);
   const calmar = maxDrawdown === 0 ? returnPct > 0 ? Infinity : 0 : returnPct / maxDrawdown;
   const totalBars = Math.max(1, candles.length);
-  const openBars = completedTrades.reduce((total, trade) => {
-    const barsHeld = Math.max(1, Math.round((trade.exit.time - trade.openTime) / estBarMs));
-    return total + barsHeld;
-  }, 0);
   const exposurePct = openBars / totalBars;
-  const holdDurationsMinutes = completedTrades.map(
-    (trade) => (trade.exit.time - trade.openTime) / (1e3 * 60)
-  );
   const avgHoldMin = mean(holdDurationsMinutes);
   const equitySeries = eqSeries && eqSeries.length ? eqSeries : buildEquitySeriesFromLegs({ legs, equityStart });
   const dailyReturnsSeries = dailyReturns(equitySeries);
@@ -272,12 +303,6 @@ function buildMetrics({
   const sharpeDaily = dailyStd === 0 ? dailyReturnsSeries.length ? Infinity : 0 : mean(dailyReturnsSeries) / dailyStd;
   const sortinoDaily = sortino(dailyReturnsSeries);
   const dailyWinRate = dailyReturnsSeries.length ? dailyReturnsSeries.filter((value) => value > 0).length / dailyReturnsSeries.length : 0;
-  const longTrades = completedTrades.filter((trade) => trade.side === "long");
-  const shortTrades = completedTrades.filter((trade) => trade.side === "short");
-  const longRs = longTrades.map(tradeRMultiple);
-  const shortRs = shortTrades.map(tradeRMultiple);
-  const longPnls = longTrades.map((trade) => trade.exit.pnl);
-  const shortPnls = shortTrades.map((trade) => trade.exit.pnl);
   const rDistribution = {
     p10: percentile(tradeRs, 0.1),
     p25: percentile(tradeRs, 0.25),
@@ -294,21 +319,21 @@ function buildMetrics({
   };
   const sideBreakdown = {
     long: {
-      trades: longTrades.length,
-      winRate: longTrades.length ? longTrades.filter((trade) => trade.exit.pnl > 0).length / longTrades.length : 0,
-      avgPnL: mean(longPnls),
+      trades: longTradesCount,
+      winRate: longTradesCount ? longTradeWins / longTradesCount : 0,
+      avgPnL: longTradesCount ? longPnLSum / longTradesCount : 0,
       avgR: mean(longRs)
     },
     short: {
-      trades: shortTrades.length,
-      winRate: shortTrades.length ? shortTrades.filter((trade) => trade.exit.pnl > 0).length / shortTrades.length : 0,
-      avgPnL: mean(shortPnls),
+      trades: shortTradesCount,
+      winRate: shortTradesCount ? shortTradeWins / shortTradesCount : 0,
+      avgPnL: shortTradesCount ? shortPnLSum / shortTradesCount : 0,
       avgR: mean(shortRs)
     }
   };
   return {
     trades: completedTrades.length,
-    winRate: completedTrades.length ? winningTrades.length / completedTrades.length : 0,
+    winRate: completedTrades.length ? winningTradeCount / completedTrades.length : 0,
     profitFactor: profitFactorPositions,
     expectancy,
     totalR,
@@ -330,8 +355,8 @@ function buildMetrics({
     startEquity: equityStart,
     profitFactor_pos: profitFactorPositions,
     profitFactor_leg: profitFactorLegs,
-    winRate_pos: completedTrades.length ? winningTrades.length / completedTrades.length : 0,
-    winRate_leg: legs.length ? winningLegs.length / legs.length : 0,
+    winRate_pos: completedTrades.length ? winningTradeCount / completedTrades.length : 0,
+    winRate_leg: legs.length ? winningLegCount / legs.length : 0,
     sharpeDaily,
     sortinoDaily,
     sideBreakdown,