openalgo-script 0.2.0 → 0.5.0

package/src/core/accounting/equity.ts

@@ -0,0 +1,314 @@
+/**
+ * The equity curve: one point per bar in the report window.
+ *
+ * **Marked to the close and to nothing else.** An intrabar extreme is a price
+ * the strategy could not have acted on, so it is not a profit it had, and a
+ * curve drawn through the extremes flatters every run that ever held a losing
+ * position. Where a bar's close is absent the previous mark carries and the
+ * point says so, rather than a zero a reader would compare against.
+ *
+ * **Drawdown is stated on equity including open profit**, and the basis is
+ * carried on every point rather than left to the reader: `drawdown` is the
+ * distance below the running peak, zero or negative, and `drawdownPercent` is
+ * that distance against the peak. A report whose drawdown basis is not written
+ * down is a report whose worst figure means a different thing to each reader.
+ *
+ * ## What the curve is folded from, and when each figure lands
+ *
+ * A trade list and a list of bar closes, and nothing else. A trade carries its
+ * own gross, its own charges and the two bars it lived between, so the fold is
+ * a sweep: bars in the order they arrived, trades in the order they opened.
+ *
+ * - **A trade's charges land on the bar it opened.** The trade list does not
+ *   carry the timing of the individual fills underneath it, so the cost has to
+ *   land somewhere, and the open is the one place that is never later than the
+ *   truth: an entry charge is paid the moment the trade is taken on, and an
+ *   exit charge cannot be paid before it. The alternative, landing the whole
+ *   cost at the close, shows a run carrying a position for two hundred bars as
+ *   having paid nothing for it, and leaves a trade that never closed paying
+ *   nothing at all.
+ * - **A trade's gross lands on the bar it closed**, because that is the bar it
+ *   stopped being an opinion and became a number. While it is open it is in
+ *   `openProfit` instead, marked to the close, and the two never overlap.
+ *
+ * So the last point of a full run carries every charge the run paid, open
+ * trades included, and every gross it realised, which is an identity the
+ * summary is asserted against rather than assumed to share.
+ *
+ * ## What a trade list cannot say, said here rather than discovered later
+ *
+ * A trade holds one entry price weighted over its entry fills and one exit
+ * price weighted over its exit fills, so a trade whose size changed while it
+ * was open is not visible in it: the size a trade held between its open and its
+ * close is the size it ended up entering, at the average price it ended up
+ * entering at. Both directions are wrong and they are wrong differently.
+ *
+ * - **A partial close** is marked at the full size from the bar the reduction
+ *   settled on, so the open profit of the part already closed is counted twice
+ *   over, once here and once in the realised total.
+ * - **A scale-in is the worse of the two**, because it is wrong from the
+ *   beginning rather than from the middle. A trade that buys a hundred at ten
+ *   and another hundred at twenty is marked, from the bar it first opened, as
+ *   two hundred units bought at fifteen. On the bars before the second entry it
+ *   is therefore marked five points under water on units it did not hold, and
+ *   the curve reports a drawdown the account never had. The summary's
+ *   `maxDrawdown` and `maxDrawdownPercent` are folded from this curve, so a
+ *   pyramiding strategy is reported as having risked more than it did.
+ *
+ * Neither reaches the realised total, which is folded from the fills: what is
+ * affected is `openProfit`, `exposure`, `equity` and every drawdown figure
+ * taken off the curve, on the bars a trade's size was not what it ended as.
+ *
+ * A curve folded from the fills rather than from the trades would have neither,
+ * and that is what fixes it: it needs each entry, exit and charge to land on
+ * the bar it settled on, which is a different fold from this one rather than a
+ * correction to it. It is written here because a limitation nobody wrote down
+ * is a limitation somebody finds inside a report they had already believed.
+ *
+ * ## Two preconditions, both of them the caller's
+ *
+ * The trades arrive in the order they opened, which is the order `Trade.index`
+ * states, and the bars arrive in the order they were loaded. Both are swept
+ * with a pointer rather than searched, because a report over fifty thousand
+ * bars that rescans its trade list on every one of them is a report nobody
+ * waits for.
+ *
+ * ## And a percentage here is a fraction of its basis
+ *
+ * `drawdownPercent` is `drawdown / runningPeak`, which is a fraction: a
+ * hundredth of a percent down is written `-0.0001` and not `-0.01`. One
+ * convention for every figure in this module that divides, because two figures
+ * spelled the same way in two units is a number a reader gets wrong once and
+ * never trusts again. The multiplication by a hundred belongs to whatever
+ * prints it.
+ */
+import type { BarMark, Contract, Money } from './shapes.js';
+import type { Trade } from './trades.js';
+
+/** One report bar's standing, folded from the fills settled up to it. */
+export interface EquityPoint {
+  readonly barIndex: number;
+  readonly time: number | null;
+  /** Cumulative gross of closed trades. */
+  readonly realised: Money;
+  /** Cumulative. */
+  readonly charges: Money;
+  /** Marked to this bar's close. */
+  readonly openProfit: Money;
+  /** capital + realised - charges. */
+  readonly cash: Money;
+  /** cash + openProfit. */
+  readonly equity: Money;
+  /** The open position's magnitude at this close. */
+  readonly exposure: Money;
+  /** equity - runningPeak, zero or negative. */
+  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;
+}
+
+/**
+ * Whether this trade was still held at the close of this bar.
+ *
+ * The boundaries are the whole of the rule and both are decisions. A trade is
+ * held from the close of the bar it opened on, because an entry that settled
+ * during a bar is a position that bar ended holding. It is not held at the
+ * close of the bar it closed on, because that bar ended flat. So a trade
+ * opened and closed inside one bar is held at no close at all, which is what a
+ * run that was flat at every mark should report.
+ *
+ * Every figure in this module that asks which trades are open asks it here, so
+ * the curve, the exposure and the count of bars in the market cannot come to
+ * three different answers about one bar.
+ */
+export function openOnBar(trade: Trade, barIndex: number): boolean {
+  if (barIndex < trade.openedOnBar) return false;
+  return trade.closedOnBar === null || barIndex < trade.closedOnBar;
+}
+
+/**
+ * A ratio against a basis that may not be there to divide by.
+ *
+ * Capital of zero and a peak of zero are both reachable, and both turn an
+ * honest division into a value JSON cannot carry: a report whose worst figure
+ * comes back `null` from a round trip is worse than one that says zero. A basis
+ * that is not positive has no ratio to state, so the figure beside it, which is
+ * money and is always true, is the one a reader is left with.
+ */
+export function ratioOf(value: number, basis: number): number {
+  return basis > 0 ? value / basis : 0;
+}
+
+/**
+ * The curve, one point per report bar, in the order the bars arrived.
+ *
+ * Warmup bars are swept and not reported: their orders were real, so a trade
+ * opened during the warmup is already in the fold at the first point, with its
+ * charges already paid and its position already marked. A curve that began its
+ * fold at the first report bar would lose both, and would lose them silently.
+ *
+ * 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[],
+  marks: readonly BarMark[],
+  contract: Contract,
+  capital: Money,
+): readonly EquityPoint[] {
+  const points: EquityPoint[] = [];
+  let held: Trade[] = [];
+  let next = 0;
+  let realised = 0;
+  let charges = 0;
+  let peak = capital;
+  let trough = capital;
+  let mark: number | null = null;
+
+  for (const bar of marks) {
+    // Opened by this bar, charges and all. The pointer is why the trades have
+    // to arrive in the order they opened.
+    while (next < trades.length) {
+      const opening = trades[next];
+      if (opening === undefined || opening.openedOnBar > bar.barIndex) break;
+      charges += opening.charges;
+      held.push(opening);
+      next += 1;
+    }
+
+    // Closed by this bar, gross and all. A trade that opened and closed inside
+    // one bar is taken on and given up here in that order, so its cost and its
+    // gross are both in this point and its position is in none.
+    let closedHere = false;
+    for (const trade of held) {
+      if (closedBy(trade, bar.barIndex)) {
+        realised += trade.grossProfit;
+        closedHere = true;
+      }
+    }
+    if (closedHere) held = held.filter((trade) => !closedBy(trade, bar.barIndex));
+
+    // A close the host did not have leaves the previous mark standing. It is
+    // carried across the warmup boundary too, so the first report bar of a run
+    // whose close is absent is marked at the last price there was.
+    if (bar.close !== null) mark = bar.close;
+    if (!bar.inReport) continue;
+
+    let openProfit = 0;
+    let exposure = 0;
+    for (const trade of held) {
+      // Before the first close there has ever been, a trade is marked at its
+      // own entry: no profit, and the position still visible in the exposure.
+      const at = mark ?? trade.entryPrice;
+      const direction = trade.side === 'long' ? 1 : -1;
+      openProfit += direction * (at - trade.entryPrice) * trade.units * contract.pointValue;
+      exposure += Math.abs(trade.units * at * contract.pointValue);
+    }
+
+    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,
+      realised,
+      charges,
+      openProfit,
+      cash,
+      equity,
+      exposure,
+      drawdown,
+      drawdownPercent: ratioOf(drawdown, peak),
+      runUp,
+      runUpPercent: ratioOf(runUp, trough),
+    });
+  }
+
+  return points;
+}
+
+/**
+ * How many of these bars ended with something held.
+ *
+ * Swept rather than searched: a sorted list of the bars trades opened on, a
+ * sorted list of the bars they closed on, and the running difference between
+ * how many of each have gone by. That is the boundary rule `openOnBar` states,
+ * arrived at from the other side, and the two are asserted to agree over a
+ * generated corpus rather than trusted to. A count that disagrees with the
+ * curve beside it about which bars were in the market is exactly the kind of
+ * defect a reader finds by adding two of the printed figures up.
+ */
+export function barsInMarketOver(
+  trades: readonly Trade[],
+  equity: readonly EquityPoint[],
+): number {
+  const opens = trades.map((trade) => trade.openedOnBar).sort(ascending);
+  const closes = trades
+    .filter((trade) => trade.closedOnBar !== null)
+    .map((trade) => trade.closedOnBar ?? 0)
+    .sort(ascending);
+
+  let opened = 0;
+  let closed = 0;
+  let live = 0;
+  let bars = 0;
+  for (const point of equity) {
+    while (opened < opens.length && (opens[opened] ?? 0) <= point.barIndex) {
+      live += 1;
+      opened += 1;
+    }
+    while (closed < closes.length && (closes[closed] ?? 0) <= point.barIndex) {
+      live -= 1;
+      closed += 1;
+    }
+    if (live > 0) bars += 1;
+  }
+  return bars;
+}
+
+/** Whether this bar is the bar the trade closed on, or one after it. */
+function closedBy(trade: Trade, barIndex: number): boolean {
+  return trade.closedOnBar !== null && trade.closedOnBar <= barIndex;
+}
+
+/** Smallest first, said once, because a sort without a comparison sorts text. */
+function ascending(left: number, right: number): number {
+  return left - right;
+}

package/src/core/accounting/index.ts

@@ -0,0 +1,51 @@
+/**
+ * The money: what a run made, what it cost, and what that is worth knowing.
+ *
+ * **This module imports no engine and no emitter, and it never will.** It is
+ * arithmetic over portable data: a list of settled fills, a list of bar closes,
+ * a charge schedule and the contract the run was carried out under. Two things
+ * follow from that and both of them are the reason for it.
+ *
+ * A stored record can be reported again with no engine present, which is what
+ * makes a run record a conformance case rather than a souvenir. And the engine
+ * can call this, when the day comes that a script may read its own equity,
+ * without a cycle and without a second implementation of any of these formulas
+ * sitting inside the execution path disagreeing with this one.
+ *
+ * The door names what a caller may use. The fold itself, the cost basis, the
+ * round trip state machine and the statistics stay behind it: they are one
+ * algorithm with one caller.
+ *
+ * Behaviour lands beside these shapes, each call in the file its type is in.
+ * The cost model is here: `chargeFor` is what one fill came to,
+ * `scheduleFromDeclaration` is the declaration's own commission as the one kind
+ * of schedule this module evaluates, and `scheduleProblem` is what a schedule
+ * is refused for before the first bar. The round trips, the equity curve, the
+ * statistics and the report land beside their own shapes the same way.
+ *
+ * The shapes were agreed before any of it computed, because they are what the
+ * engine, the backtest driver and a second engine all have to agree about.
+ */
+export { chargeFor, scheduleFromDeclaration, scheduleProblem } from './charges.js';
+export type { BarMark, Contract, Money, RecordedFill } from './shapes.js';
+export type {
+  ChargeBase,
+  ChargeBreakdown,
+  ChargeLine,
+  ChargeSchedule,
+  ChargeSide,
+} from './charges.js';
+export { tradesOf } from './trades.js';
+export type { Trade } from './trades.js';
+export { equityOver } from './equity.js';
+export type { EquityPoint } from './equity.js';
+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';
+export type { Report } from './report.js';

package/src/core/accounting/markers.ts

@@ -0,0 +1,95 @@
+/**
+ * One marker per entry and exit fill, which is the chart's whole input.
+ *
+ * A chart draws a trade as two marks and a line between them, and everything it
+ * needs to do that is in the fills: the bar, the trade the fill belongs to, the
+ * side, the units, the price and the tag the order carried. So the markers are
+ * produced here, by the module that already knows which fill belongs to which
+ * trade, and no chart is needed to produce them and none is imported to.
+ */
+import type { RecordedFill } from './shapes.js';
+import { closedBy, openedBy } from './trades.js';
+import type { Trade } from './trades.js';
+
+/** One entry or exit fill, addressed as a chart addresses it. */
+export interface TradeMarker {
+  readonly barIndex: number;
+  readonly time: number | null;
+  readonly tradeIndex: number;
+  readonly kind: 'entry' | 'exit';
+  readonly side: 'buy' | 'sell';
+  readonly units: number;
+  readonly price: number;
+  readonly tag: string;
+}
+
+/**
+ * One marker per entry and exit fill, against the trades those fills made up.
+ *
+ * **The fill is read with the same rule the trade list read it with.**
+ * `closedBy` and `openedBy` are imported from `trades.ts` rather than restated,
+ * because a marker that called an exit an entry would draw the chart the report
+ * contradicts. A fill that carried a reference through zero is both: it closes
+ * the trade the reference held and opens the next one, so it produces two
+ * markers, in that order, which is the order the trade list folded it in.
+ *
+ * **A trade is found by its reference and by the order it opened**, never by
+ * the bar it opened on: a reference that went to zero and was entered again on
+ * the same bar is two trades, and addressing them by bar would put both
+ * markers on the first. The trades are walked once per reference, oldest first,
+ * which is the order `tradesOf` built them in.
+ *
+ * The count is an identity rather than a claim: the markers of one trade are
+ * its `entries` plus its `exits`, and a test asserts it over the same fills.
+ */
+export function markersOf(
+  fills: readonly RecordedFill[],
+  trades: readonly Trade[],
+): readonly TradeMarker[] {
+  const ordered = fills.slice().sort((a, b) => a.seq - b.seq);
+  const queues = new Map<number, Trade[]>();
+  for (const trade of trades) {
+    const held = queues.get(trade.positionRef) ?? [];
+    held.push(trade);
+    queues.set(trade.positionRef, held);
+  }
+
+  const out: TradeMarker[] = [];
+  for (const fill of ordered) {
+    const queue = queues.get(fill.positionRef) ?? [];
+    const closing = closedBy(fill.refSizeBefore, fill.refSizeAfter);
+    const opening = openedBy(fill.refSizeBefore, fill.refSizeAfter);
+
+    if (closing > 0) {
+      const held = queue[0];
+      if (held !== undefined) out.push(markerFor(fill, held.index, 'exit', closing));
+      // The trade the reference held is finished by a fill that closed the
+      // whole of it, and the next trade on that reference is the one the fills
+      // after this belong to.
+      if (held !== undefined && (opening > 0 || fill.refSizeAfter === 0)) queue.shift();
+    }
+    if (opening > 0) {
+      const held = queue[0];
+      if (held !== undefined) out.push(markerFor(fill, held.index, 'entry', opening));
+    }
+  }
+  return out;
+}
+
+function markerFor(
+  fill: RecordedFill,
+  tradeIndex: number,
+  kind: 'entry' | 'exit',
+  units: number,
+): TradeMarker {
+  return {
+    barIndex: fill.barIndex,
+    time: fill.barTime,
+    tradeIndex,
+    kind,
+    side: fill.side,
+    units,
+    price: fill.price,
+    tag: fill.tag,
+  };
+}

package/src/core/accounting/monthly.ts

@@ -0,0 +1,137 @@
+/**
+ * The month by month table, bucketed in UTC from bar times.
+ *
+ * **UTC, and it says so on the type.** A calendar month in the instrument's own
+ * timezone would need the session machinery and the instrument's calendar, and
+ * a table that silently buckets a trade into the wrong month is worse than one
+ * that states the basis it used. No timezone library, and no pretence of the
+ * instrument's calendar.
+ */
+import type { EquityPoint } from './equity.js';
+import type { Money } from './shapes.js';
+import type { Trade } from './trades.js';
+
+/** One calendar month of the run, in UTC. */
+export interface MonthlyReturn {
+  readonly year: number;
+  /** 1 to 12, UTC. */
+  readonly month: number;
+  readonly netProfit: Money;
+  /** Against the equity at the month's first bar. */
+  readonly returnPercent: number;
+  readonly trades: number;
+}
+
+/**
+ * The months a run passed through, in the order it passed through them.
+ *
+ * **A month holds the change in equity across the closes inside it.** The first
+ * point of the curve has nothing before it to be compared with, so it opens the
+ * table rather than contributing to it, and every later point contributes what
+ * it moved from the point before. The consequence is an identity rather than a
+ * claim: the months add up to the equity at the last point less the equity at
+ * the first, and nothing that happened during the warmup is attributed to a
+ * month it did not happen in.
+ *
+ * `returnPercent` is that change over the equity at the month's first bar,
+ * which is the basis this table states and the reason the figure is a fraction
+ * rather than a fraction times a hundred: `drawdownPercent` beside it is
+ * `drawdown / peak`, and one report with two conventions is a report a reader
+ * has to check every figure of.
+ *
+ * `trades` counts the trades that closed inside the month, by the time they
+ * closed. An open trade is in no month, because the month it will be counted in
+ * is not decided yet.
+ *
+ * **A point with no time is in no month.** A bucket is a calendar fact and a
+ * bar with no time states no calendar, so such a point carries its change into
+ * the month in force rather than opening one, and where none is in force it is
+ * outside the table altogether. That is the honest reading: bucketing it by the
+ * month that happened to come before would put money in a month on the strength
+ * of nothing.
+ */
+export function monthlyOver(
+  equity: readonly EquityPoint[],
+  trades: readonly Trade[],
+): readonly MonthlyReturn[] {
+  const buckets: Bucket[] = [];
+  let previous: EquityPoint | undefined;
+  let current: Bucket | undefined;
+
+  for (const point of equity) {
+    const at = monthOf(point.time);
+    if (at !== null && (current === undefined || current.year !== at.year || current.month !== at.month)) {
+      // The equity this month started from, which is where the previous month
+      // left the account and not where this one's first bar closed. Taking the
+      // opening point's own equity put the month's first move into the
+      // numerator and into the denominator at once: a February that doubled a
+      // thousand pounds reported fifty percent, because the gain was divided by
+      // the two thousand it had already produced.
+      current = {
+        year: at.year,
+        month: at.month,
+        netProfit: 0,
+        basis: previous === undefined ? point.equity : previous.equity,
+        trades: 0,
+      };
+      buckets.push(current);
+    }
+    if (previous !== undefined && current !== undefined) {
+      current.netProfit += point.equity - previous.equity;
+    }
+    previous = point;
+  }
+
+  for (const trade of trades) {
+    const at = monthOf(trade.closedAt);
+    if (at === null) continue;
+    const bucket = buckets.find((one) => one.year === at.year && one.month === at.month);
+    if (bucket !== undefined) bucket.trades += 1;
+  }
+
+  return buckets.map((one) => ({
+    year: one.year,
+    month: one.month,
+    netProfit: one.netProfit,
+    returnPercent: one.basis > 0 ? one.netProfit / one.basis : 0,
+    trades: one.trades,
+  }));
+}
+
+/** One month while it is being filled. */
+interface Bucket {
+  readonly year: number;
+  readonly month: number;
+  netProfit: Money;
+  /** The equity at the month's first bar, which the return is measured against. */
+  readonly basis: Money;
+  trades: number;
+}
+
+/**
+ * The calendar month an instant falls in, in UTC and in no other zone.
+ *
+ * Decomposed rather than formatted, so no locale, no zone table and no library
+ * is involved: the same instant produces the same month on every machine this
+ * ever runs on.
+ */
+function monthOf(time: number | null): { readonly year: number; readonly month: number } | null {
+  if (time === null || !Number.isFinite(time) || Math.abs(time) > LATEST_INSTANT) return null;
+  const at = new Date(time);
+  return { year: at.getUTCFullYear(), month: at.getUTCMonth() + 1 };
+}
+
+/**
+ * The furthest either way an instant can be and still name a month.
+ *
+ * A finite number outside it decomposes to NaN rather than throwing, and a NaN
+ * year never equals the next one, so every point opened a bucket of its own and
+ * a fifty thousand bar run produced fifty thousand rows of NaN. The canonical
+ * writer then threw a bare error with no code on them, out of core, on a path a
+ * host could not tell from an internal fault. The mistake that gets here is
+ * ordinary: bar times supplied in nanoseconds rather than milliseconds.
+ *
+ * A point whose time names no month contributes to no month, which is what an
+ * absent time already did.
+ */
+const LATEST_INSTANT = 8.64e15;