openalgo-script 0.4.0 → 0.5.0

package/src/core/accounting/analysis.ts

@@ -0,0 +1,188 @@
+/**
+ * The trades taken apart: by direction, by extreme, and by run.
+ *
+ * The summary answers what the whole run did. Three questions it cannot answer
+ * are asked here, and each of them is a question about whether the summary
+ * means what it looks like it means.
+ *
+ * **Which side made the money.** A run whose long trades paid for its short
+ * ones reports a healthy net and is two strategies, one of which is losing. The
+ * summary cannot show that, because every figure in it is folded over both
+ * sides at once. Splitting it is not a refinement of the headline number, it is
+ * the first thing that can contradict it.
+ *
+ * **Whether one trade is the result.** A hundred trades and a profit factor of
+ * two reads as an edge until the largest win is the whole of the net. The
+ * expectancy's standard error already says how wide the spread is; the largest
+ * win and the largest loss say where the width came from, which is the part a
+ * reader can act on.
+ *
+ * **What the run of losses was.** The deepest drawdown is a money figure and
+ * the longest one is a bar count, and neither is the number that actually stops
+ * somebody trading a strategy. That number is how many times in a row it was
+ * wrong. It is not derivable from anything in the summary: the same win rate
+ * over the same trades gives a streak of two or a streak of eleven depending on
+ * an ordering the summary folds away.
+ *
+ * ## Every figure here is over closed trades, and that is the whole rule
+ *
+ * An open trade has no net to win or lose by, so it is in none of these counts,
+ * on either side, in no streak and in no extreme. `statistics.ts` has three
+ * different answers to which trades a figure is counted over, because a summary
+ * carries a capital figure and a bar count that are facts about the run rather
+ * than about its trades. Nothing here is a fact about the run, so there is one
+ * answer, and a reader can hold it.
+ *
+ * The consequence worth stating: `longCount + shortCount` is `tradeCount` and
+ * not the length of the list folded. A run holding an open position reports
+ * fewer trades here than it has, and the summary's `openTradeCount` is where
+ * the difference is accounted for.
+ */
+
+import type { Money } from './shapes.js';
+import type { Trade } from './trades.js';
+
+/** One direction's own figures, folded over that side's closed trades. */
+export interface SideAnalysis {
+  readonly count: number;
+  readonly wins: number;
+  readonly losses: number;
+  /** Exactly zero net, counted in neither half, as in the summary. */
+  readonly scratches: number;
+  /** Net after charges, which is the figure the sides are compared on. */
+  readonly netProfit: Money;
+  /** `wins / (wins + losses)`, null where this side decided nothing. */
+  readonly winRate: number | null;
+}
+
+/**
+ * The trades by direction, by extreme and by run.
+ *
+ * `long` and `short` partition the closed trades, so their counts sum to the
+ * summary's `tradeCount` and their nets sum to its `netProfit`. That is
+ * asserted rather than assumed, because a partition that stops partitioning is
+ * the defect this shape exists to make visible and it would otherwise show up
+ * as two panels that quietly disagree.
+ */
+export interface TradeAnalysis {
+  readonly long: SideAnalysis;
+  readonly short: SideAnalysis;
+  /**
+   * The best closed trade's net, zero where none closed and zero where every
+   * closed trade lost.
+   *
+   * Zero rather than null, and it is the one place here that is worth arguing
+   * about. A run whose every trade lost has no winning trade to name, and null
+   * would say so. It reports zero because the figure is read beside
+   * `largestLoss` and against `netProfit`, and a null in a column of money
+   * forces every reader of the report to handle a case that means "nothing
+   * won", which is what zero already means in this column.
+   */
+  readonly largestWin: Money;
+  /** The worst closed trade's net as a positive magnitude, zero where none lost. */
+  readonly largestLoss: Money;
+  /**
+   * The longest run of consecutive winning closed trades, in the order they
+   * closed.
+   *
+   * In the order they closed, and not the order they opened, because that is
+   * the order the account experienced them in and the streak is a fact about
+   * what the account experienced. The two orders differ whenever a trade is
+   * held across another one's whole life, which is every scaling strategy.
+   */
+  readonly maxConsecutiveWins: number;
+  /** The same, for losses. */
+  readonly maxConsecutiveLosses: number;
+}
+
+/** A side's figures under construction, before the rates are taken. */
+interface SideTally {
+  count: number;
+  wins: number;
+  losses: number;
+  scratches: number;
+  netProfit: Money;
+}
+
+function emptySide(): SideTally {
+  return { count: 0, wins: 0, losses: 0, scratches: 0, netProfit: 0 };
+}
+
+function sideOf(tally: SideTally): SideAnalysis {
+  const decided = tally.wins + tally.losses;
+  return {
+    count: tally.count,
+    wins: tally.wins,
+    losses: tally.losses,
+    scratches: tally.scratches,
+    netProfit: tally.netProfit,
+    winRate: decided === 0 ? null : tally.wins / decided,
+  };
+}
+
+/**
+ * One pass over the closed trades, in closing order.
+ *
+ * The list arrives in opening order, which is what the equity fold needs and
+ * what `tradesOf` produces. The streaks need closing order, so the closed
+ * trades are ordered here rather than anywhere else: reordering the list the
+ * caller holds would change the equity curve, and taking a second list in
+ * opening order and calling its streaks correct would be the defect this
+ * function is supposed to have caught.
+ *
+ * A trade whose net is exactly zero is a scratch, which is the summary's rule
+ * and is applied here for the same reason. A scratch **breaks** a streak
+ * without extending either one: a strategy that went right, flat, right was not
+ * right twice running, and counting the flat trade as either would make the
+ * streak a figure that depends on a rounding at the last digit.
+ */
+export function analysisOf(trades: readonly Trade[]): TradeAnalysis {
+  const long = emptySide();
+  const short = emptySide();
+  let largestWin = 0;
+  let largestLoss = 0;
+  let maxConsecutiveWins = 0;
+  let maxConsecutiveLosses = 0;
+  let winStreak = 0;
+  let lossStreak = 0;
+
+  const closed = trades.filter((trade) => !trade.isOpen).slice();
+  // A trade closes on a bar, and two can close on the same one. The opening
+  // order breaks the tie, because it is the order the list arrived in and the
+  // only other fact available: a sort that is not total gives two engines two
+  // different streaks from one list of trades.
+  closed.sort((a, b) => (a.closedOnBar ?? 0) - (b.closedOnBar ?? 0) || a.index - b.index);
+
+  for (const trade of closed) {
+    const side = trade.side === 'long' ? long : short;
+    side.count += 1;
+    side.netProfit += trade.netProfit;
+
+    if (trade.netProfit > 0) {
+      side.wins += 1;
+      if (trade.netProfit > largestWin) largestWin = trade.netProfit;
+      winStreak += 1;
+      lossStreak = 0;
+      if (winStreak > maxConsecutiveWins) maxConsecutiveWins = winStreak;
+    } else if (trade.netProfit < 0) {
+      side.losses += 1;
+      if (-trade.netProfit > largestLoss) largestLoss = -trade.netProfit;
+      lossStreak += 1;
+      winStreak = 0;
+      if (lossStreak > maxConsecutiveLosses) maxConsecutiveLosses = lossStreak;
+    } else {
+      side.scratches += 1;
+      winStreak = 0;
+      lossStreak = 0;
+    }
+  }
+
+  return {
+    long: sideOf(long),
+    short: sideOf(short),
+    largestWin,
+    largestLoss,
+    maxConsecutiveWins,
+    maxConsecutiveLosses,
+  };
+}

package/src/core/accounting/equity.ts

@@ -105,6 +105,33 @@ export interface EquityPoint {
   readonly drawdown: Money;
   /** `drawdown / runningPeak`, a fraction and not a figure times a hundred. */
   readonly drawdownPercent: number;
+  /**
+   * The distance above the running trough, zero or positive.
+   *
+   * Drawdown's mirror, and carried for the same reason drawdown is: it is the
+   * run's best stretch measured the same way its worst one is, so the two can
+   * be read against each other. A reader handed only the depth learns how bad
+   * it got and nothing about whether the run ever climbed far enough for that
+   * depth to be a giving back rather than a steady bleed.
+   */
+  readonly runUp: Money;
+  /**
+   * `runUp / runningTrough`, a fraction and not a figure times a hundred, and
+   * zero where the trough is not above zero.
+   *
+   * Not the same guard drawdown gets, because the two bases are not the same
+   * kind of number. The running peak starts at the capital and only ever rises,
+   * so a run with capital above zero has a peak above zero at every point. The
+   * running trough starts there and only ever falls, so an account that lost
+   * everything has a trough at or below zero, and from that bar on this figure
+   * is zero rather than a fraction. Zero is the wrong answer for a run that
+   * recovered, and it is reported anyway, because the alternative is a
+   * percentage against a negative basis: a positive climb reported as a
+   * negative fraction, which is the shape that once gave a profit factor of
+   * minus a half. `runUp` itself is unaffected and stays the figure to read on
+   * such a run.
+   */
+  readonly runUpPercent: number;
 }
 
 /**
@@ -150,6 +177,12 @@ export function ratioOf(value: number, basis: number): number {
  * The running peak starts at the capital rather than at the first point, so a
  * run that is down from its first bar is in drawdown at its first bar. Starting
  * it at the first point would report every run as having begun at its high.
+ *
+ * The running trough starts at the capital for the same reason and not for a
+ * symmetrical one: a run that is up from its first bar has run up from the
+ * money it was given, which is the figure a reader is measuring against. Anchor
+ * it at the first point instead and a run that gapped up on bar zero reports
+ * that gain as having come from nowhere.
  */
 export function equityOver(
   trades: readonly Trade[],
@@ -163,6 +196,7 @@ export function equityOver(
   let realised = 0;
   let charges = 0;
   let peak = capital;
+  let trough = capital;
   let mark: number | null = null;
 
   for (const bar of marks) {
@@ -208,7 +242,9 @@ export function equityOver(
     const cash = capital + realised - charges;
     const equity = cash + openProfit;
     if (equity > peak) peak = equity;
+    if (equity < trough) trough = equity;
     const drawdown = equity - peak;
+    const runUp = equity - trough;
     points.push({
       barIndex: bar.barIndex,
       time: bar.time,
@@ -220,6 +256,8 @@ export function equityOver(
       exposure,
       drawdown,
       drawdownPercent: ratioOf(drawdown, peak),
+      runUp,
+      runUpPercent: ratioOf(runUp, trough),
     });
   }
 

package/src/core/accounting/index.ts

@@ -43,6 +43,8 @@ export { monthlyOver } from './monthly.js';
 export type { MonthlyReturn } from './monthly.js';
 export { markersOf } from './markers.js';
 export type { TradeMarker } from './markers.js';
+export { analysisOf } from './analysis.js';
+export type { SideAnalysis, TradeAnalysis } from './analysis.js';
 export { summaryOf } from './statistics.js';
 export type { Summary } from './statistics.js';
 export { reportOf } from './report.js';

package/src/core/accounting/report.ts

@@ -19,6 +19,8 @@
  * structural half of keeping that decision open: when it is taken, the engine
  * calls this, and there is no second implementation to disagree with.
  */
+import { analysisOf } from './analysis.js';
+import type { TradeAnalysis } from './analysis.js';
 import { chargeFor } from './charges.js';
 import type { ChargeSchedule } from './charges.js';
 import { equityOver } from './equity.js';
@@ -36,6 +38,8 @@ import type { Trade } from './trades.js';
 /** Everything a run is reported as, and nothing a chart has to compute. */
 export interface Report {
   readonly summary: Summary;
+  /** The trades by direction, by extreme and by run. */
+  readonly analysis: TradeAnalysis;
   readonly trades: readonly Trade[];
   readonly equity: readonly EquityPoint[];
   readonly monthly: readonly MonthlyReturn[];
@@ -81,6 +85,7 @@ export function reportOf(
 
   return {
     summary,
+    analysis: analysisOf(trades),
     trades,
     equity,
     monthly: monthlyOver(equity, trades),

package/src/core/accounting/statistics.ts

@@ -121,6 +121,18 @@ export interface Summary {
   /** A bar time, never an index. */
   readonly maxDrawdownAt: number | null;
   readonly longestDrawdownBars: number;
+  /**
+   * Zero or positive, the mirror of `maxDrawdown` and read against it.
+   *
+   * The pair is the point of it. A run that made ten and gave back nine is a
+   * different strategy from one that made one and never gave any of it back,
+   * and the two report the same net. Neither figure says that on its own.
+   */
+  readonly maxRunUp: Money;
+  /** The highest point's own fraction, not the best fraction of any point. */
+  readonly maxRunUpPercent: number;
+  /** A bar time, never an index, and not the bar `maxDrawdownAt` addresses. */
+  readonly maxRunUpAt: number | null;
   readonly averageBarsHeld: number | null;
   readonly barsInMarket: number;
   readonly barCount: number;
@@ -149,6 +161,9 @@ interface Depth {
   readonly maxDrawdownPercent: number;
   readonly maxDrawdownAt: number | null;
   readonly longestDrawdownBars: number;
+  readonly maxRunUp: Money;
+  readonly maxRunUpPercent: number;
+  readonly maxRunUpAt: number | null;
 }
 
 /**
@@ -199,6 +214,9 @@ export function summaryOf(
     maxDrawdownPercent: depth.maxDrawdownPercent,
     maxDrawdownAt: depth.maxDrawdownAt,
     longestDrawdownBars: depth.longestDrawdownBars,
+    maxRunUp: depth.maxRunUp,
+    maxRunUpPercent: depth.maxRunUpPercent,
+    maxRunUpAt: depth.maxRunUpAt,
     averageBarsHeld: tally.heldCount === 0 ? null : tally.heldTotal / tally.heldCount,
     barsInMarket: barsInMarketOver(trades, equity),
     barCount: equity.length,
@@ -303,6 +321,9 @@ function depthOf(equity: readonly EquityPoint[]): Depth {
   let maxDrawdownAt: number | null = null;
   let longestDrawdownBars = 0;
   let under = 0;
+  let maxRunUp = 0;
+  let maxRunUpPercent = 0;
+  let maxRunUpAt: number | null = null;
 
   for (const point of equity) {
     if (point.drawdown < maxDrawdown) {
@@ -316,9 +337,25 @@ function depthOf(equity: readonly EquityPoint[]): Depth {
     } else {
       under = 0;
     }
+    // Strictly greater, so the earliest bar reaching the height wins the tie,
+    // which is the rule the depth above is picked by. The two figures address
+    // different bars and each addresses the first bar that reached it.
+    if (point.runUp > maxRunUp) {
+      maxRunUp = point.runUp;
+      maxRunUpPercent = point.runUpPercent;
+      maxRunUpAt = point.time;
+    }
   }
 
-  return { maxDrawdown, maxDrawdownPercent, maxDrawdownAt, longestDrawdownBars };
+  return {
+    maxDrawdown,
+    maxDrawdownPercent,
+    maxDrawdownAt,
+    longestDrawdownBars,
+    maxRunUp,
+    maxRunUpPercent,
+    maxRunUpAt,
+  };
 }
 
 /**