openalgo-script 0.2.0 → 0.5.0

package/src/core/accounting/report.ts

@@ -0,0 +1,94 @@
+/**
+ * The report: what a run came to, folded from its fills and its bar closes.
+ *
+ * **The evaluation order is fixed here and nowhere else**, because a report
+ * that is right to eleven digits and different in the twelfth fails a
+ * conformance comparison months later on somebody else's engine, and the cause
+ * is always a line nobody thought was arithmetic. Fills in `seq` order, charge
+ * lines in declaration order, one rounding per fill total, no collection
+ * re-summed in another order, no dependence on a map's iteration order, no wall
+ * clock and no random number generator anywhere in this module.
+ *
+ * **What the report is not is read by a script.** The money entries of the
+ * `pos` namespace stay planned and go on refusing at the call. The moment a
+ * script can read its own equity mid-run, the money layer joins the execution
+ * path, and therefore joins the conformance surface, and every formula in this
+ * module has to be agreed by a second engine before a script may branch on it.
+ * This module computes the money after the fact from a record; whether a script
+ * may read it is a later decision. That this module imports no engine is the
+ * 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';
+import type { EquityPoint } from './equity.js';
+import { monthlyOver } from './monthly.js';
+import type { MonthlyReturn } from './monthly.js';
+import { markersOf } from './markers.js';
+import type { TradeMarker } from './markers.js';
+import type { BarMark, Contract, Money, RecordedFill } from './shapes.js';
+import { summaryOf } from './statistics.js';
+import type { Summary } from './statistics.js';
+import { tradesOf } from './trades.js';
+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[];
+  readonly markers: readonly TradeMarker[];
+}
+
+/**
+ * The whole report, folded from the fills, the bar closes and the schedule.
+ *
+ * **One pass, in one order, and the order is the result.** The fills are put in
+ * `seq` order once, here, and every fold below reads that same list: the
+ * charges are computed in it, the trades are built from it, the curve is marked
+ * along it and the markers come off it. A second ordering anywhere would be a
+ * report that is right to eleven digits and different in the twelfth on
+ * somebody else's engine, which is the failure this module is shaped to make
+ * impossible rather than unlikely.
+ *
+ * **A charge belongs to the fill that incurred it.** `chargeFor` rounds one
+ * fill's total once, and nothing here rounds it again or re-sums the collection
+ * in another order, so `sum(trade.charges)` and `summary.charges` are the same
+ * money and a test asserts it rather than a page claiming it.
+ *
+ * A run carried out under no schedule at all is charged nothing, which is a
+ * study of the strategy before costs and is a thing worth being able to ask
+ * for. It is not a default: `scheduleFromDeclaration` is what a run under the
+ * declaration's own commission uses, and the caller states which it wants.
+ */
+export function reportOf(
+  fills: readonly RecordedFill[],
+  marks: readonly BarMark[],
+  schedule: ChargeSchedule | null,
+  contract: Contract,
+  capital: Money,
+): Report {
+  const ordered = fills.slice().sort((a, b) => a.seq - b.seq);
+  const charges = ordered.map((fill) =>
+    schedule === null ? 0 : chargeFor(schedule, fill, contract).total,
+  );
+
+  const trades = tradesOf(ordered, charges, marks, contract);
+  const equity = equityOver(trades, marks, contract, capital);
+  const summary = summaryOf(trades, equity, contract, capital);
+
+  return {
+    summary,
+    analysis: analysisOf(trades),
+    trades,
+    equity,
+    monthly: monthlyOver(equity, trades),
+    markers: markersOf(ordered, trades),
+  };
+}

package/src/core/accounting/shapes.ts

@@ -0,0 +1,73 @@
+/**
+ * The atoms the money is folded from: a fill, a contract and a bar's close.
+ *
+ * **Everything in this module is portable data.** No class, no function, no
+ * object reference, no absent field, no map and no date: a shape here is what
+ * `JSON.parse` gives back, so a report can be computed here, stored by a
+ * platform, sent to another process and recomputed there without this
+ * implementation being present. That is not a convenience. A run record is the
+ * conformance case a second engine is handed, and a case that can only be read
+ * by the engine that wrote it proves nothing about either.
+ *
+ * **A fill is the only thing money is folded from.** Not a position, not a
+ * ledger row, not a running total the engine happened to be holding: the fills
+ * the engine settled, in the order it settled them, each naming the position
+ * reference it moved and the size of that reference either side of the
+ * settlement. Every figure in a report is a function of that list and of the
+ * bars it is marked against, which is what makes a report reproducible from a
+ * record with no engine in the room.
+ */
+
+/**
+ * Money, in the contract's own currency.
+ *
+ * A number rather than a type of its own, because a type of its own would be a
+ * class and a class does not survive `JSON.parse`. The rounding is stated once,
+ * on the contract, and applied once per fill total.
+ */
+export type Money = number;
+
+/**
+ * The instrument facts a run was carried out under, as the host stated them.
+ *
+ * A snapshot rather than a reference. An instrument's lot size and tick size
+ * change, and a report recomputed months later under today's facts would be a
+ * different study wearing the same name, so the facts travel with the run.
+ */
+export interface Contract {
+  readonly symbol: string | null;
+  readonly exchange: string | null;
+  readonly currency: string;
+  readonly tickSize: number | null;
+  readonly lotSize: number | null;
+  /** Money per 1.0 of price per unit; 1 when the host states none. */
+  readonly pointValue: number;
+  /** Money rounding digits, half to even, once per fill total. */
+  readonly digits: number;
+}
+
+/** One settled fill. Every money figure is folded from these and nothing else. */
+export interface RecordedFill {
+  readonly seq: number;
+  readonly intentId: number;
+  readonly orderRef: string;
+  readonly tag: string;
+  readonly positionRef: number;
+  readonly side: 'buy' | 'sell';
+  /** Positive, this fill's own quantity. */
+  readonly units: number;
+  readonly price: number;
+  readonly barIndex: number;
+  readonly barTime: number | null;
+  readonly refSizeBefore: number;
+  readonly refSizeAfter: number;
+}
+
+/** One bar as the report marks against it. Close only: 17.4 marks to the close. */
+export interface BarMark {
+  readonly barIndex: number;
+  readonly time: number | null;
+  readonly close: number | null;
+  /** False for a warmup bar. */
+  readonly inReport: boolean;
+}

package/src/core/accounting/statistics.ts

@@ -0,0 +1,387 @@
+/**
+ * The summary, and the two figures in it that decide whether a run means
+ * anything.
+ *
+ * **Win rate is over closed trades, on net profit after charges**, and a trade
+ * whose net is exactly zero is a scratch counted in neither half. It is null
+ * where nothing closed rather than zero, because zero is a number a reader
+ * compares against and "nothing has closed yet" is not a losing run.
+ *
+ * **Expectancy is money per closed trade**, and it has two spellings that must
+ * agree: the win rate against the average win and the average loss, and the net
+ * profit over the trade count. Two spellings of one figure that disagree is how
+ * a report loses its reader, so one of them is the computation and the other is
+ * a test, and the test says which sequence of roundings it allows for.
+ *
+ * **And its standard error is what answers the question a comparison asks.**
+ * The sample standard deviation of per-trade net over the square root of the
+ * trade count is what turns "this run made more" into "this run made more than
+ * the noise", and without it a difference of two percent over eleven trades
+ * reads like a result.
+ *
+ * Bar times rather than bar indices, wherever a figure addresses a bar: loading
+ * more history shifts every index, so a report that addresses a bar by index
+ * changes when the warmup changes.
+ *
+ * ## Which trades a figure is counted over, which is three different answers
+ *
+ * A summary folds a list holding closed trades and open ones together, and
+ * almost every defect this file can have is a figure counted over the wrong
+ * half of it.
+ *
+ * - **Net profit, and everything derived from it**, is over closed trades. An
+ *   open trade's net is its charges so far with no gross against them, so
+ *   counting it would report a run holding a winner as having lost money.
+ * - **Charges are over every trade**, open ones included, because the money
+ *   left the account whether or not the position came back. This is the figure
+ *   the equity curve's last point carries, and the two are asserted equal.
+ * - **The drawdown figures are over the curve** and not over the trades at all.
+ *   A drawdown is a thing equity did between two trades as often as during one.
+ *
+ * ## The cases where a statistic is not a number
+ *
+ * Every one of them is a division, and every one of them is answered here
+ * rather than left to arrive as a value JSON turns into `null`:
+ *
+ * - **Nothing closed.** The win rate is null, which is a different claim from
+ *   zero. Expectancy and its error are zero, because the type is money and
+ *   money is not nullable, and `tradeCount` beside them is the field that says
+ *   whether they mean anything.
+ * - **One closed trade.** A sample of one has no spread, so the standard error
+ *   is zero. Zero here means not measurable, never measured: anything dividing
+ *   by it checks the trade count first.
+ * - **Every closed trade a scratch.** There is no denominator for a win rate,
+ *   so it is null for the same reason as nothing closed.
+ * - **Nothing lost.** The profit factor is null rather than an infinity, which
+ *   is the same decision `spec/conformance.md` takes about absence: a value
+ *   that does not survive being written down is not a value a report may hold.
+ * - **Everything lost.** The profit factor is zero, expectancy is negative, the
+ *   average win is zero, and none of the four is a division by zero.
+ */
+import { barsInMarketOver, ratioOf } from './equity.js';
+import type { EquityPoint } from './equity.js';
+import type { Contract, Money } from './shapes.js';
+import type { Trade } from './trades.js';
+
+/** What the whole run came to. */
+export interface Summary {
+  readonly capital: Money;
+  readonly currency: string;
+  readonly netProfit: Money;
+  /** Sum of winning trades, before charges. */
+  readonly grossProfit: Money;
+  /**
+   * The losing trades' gross, as a magnitude, and it can come out at or below
+   * zero.
+   *
+   * A trade wins or loses on its net after charges and contributes its gross
+   * here, so a trade whose gross was positive and whose charges took it under
+   * lands in the losses carrying a positive gross, which lowers this figure and
+   * with few enough trades beside it takes it to zero or past it. `tallyOf`
+   * says why that is preferred to counting one trade as a loser in one figure
+   * and a winner in another. It is written here because it was documented as a
+   * positive magnitude and is not one, and a reader dividing by it was handed a
+   * negative profit factor with nothing saying that could happen.
+   */
+  readonly grossLoss: Money;
+  readonly charges: Money;
+  /** `netProfit / capital`, a fraction and not a figure times a hundred. */
+  readonly returnPercent: number;
+  /** Closed only. */
+  readonly tradeCount: number;
+  readonly openTradeCount: number;
+  readonly wins: number;
+  readonly losses: number;
+  /** Exactly zero net. */
+  readonly scratches: number;
+  /** wins / (wins + losses), null when none closed. */
+  readonly winRate: number | null;
+  readonly averageWin: Money;
+  /** Positive magnitude. */
+  readonly averageLoss: Money;
+  /** Money per closed trade. */
+  readonly expectancy: Money;
+  readonly expectancyStandardError: Money;
+  /**
+   * Gross profit over gross loss, or null where there is no ratio to take.
+   *
+   * Null when the gross loss is not above zero: a run with no losing trade has
+   * nothing to divide by, and one whose losses cost less in gross than their
+   * charges has a denominator at or below zero. A profit factor is a
+   * non-negative ratio everywhere it is used, so a negative one is not a
+   * surprising value, it is a number nobody can act on. It used to be
+   * reported: two trades, one charged into a loss on a positive gross, gave a
+   * profit factor of -0.5.
+   */
+  readonly profitFactor: number | null;
+  /** Zero or negative, the same sign the curve states it with. */
+  readonly maxDrawdown: Money;
+  /** The deepest point's own fraction, not the worst fraction of any point. */
+  readonly maxDrawdownPercent: number;
+  /** 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;
+}
+
+/** The closed trades split three ways, and the sums each half contributes. */
+interface Tally {
+  readonly netProfit: Money;
+  readonly grossProfit: Money;
+  readonly grossLoss: Money;
+  readonly charges: Money;
+  readonly tradeCount: number;
+  readonly openTradeCount: number;
+  readonly wins: number;
+  readonly losses: number;
+  readonly scratches: number;
+  readonly winTotal: Money;
+  readonly lossTotal: Money;
+  readonly heldTotal: number;
+  readonly heldCount: number;
+}
+
+/** The deepest point of the curve, and how long the run stayed under water. */
+interface Depth {
+  readonly maxDrawdown: Money;
+  readonly maxDrawdownPercent: number;
+  readonly maxDrawdownAt: number | null;
+  readonly longestDrawdownBars: number;
+  readonly maxRunUp: Money;
+  readonly maxRunUpPercent: number;
+  readonly maxRunUpAt: number | null;
+}
+
+/**
+ * The whole run in one shape, folded from its trades and its own curve.
+ *
+ * The curve is passed in rather than recomputed, because a summary that folded
+ * its own would be a second equity curve with a second set of rounding, and the
+ * first disagreement between them would be a drawdown figure that no point in
+ * the reported curve ever reached.
+ */
+export function summaryOf(
+  trades: readonly Trade[],
+  equity: readonly EquityPoint[],
+  contract: Contract,
+  capital: Money,
+): Summary {
+  const tally = tallyOf(trades);
+  const depth = depthOf(equity);
+  const decided = tally.wins + tally.losses;
+
+  // Net over the closed count, and nothing else, because this is the figure the
+  // other spelling is checked against. The win rate spelling divides by the
+  // decided trades instead, so the two are the same number exactly when no
+  // trade scratched, and `tests/accounting/statistics.test.ts` asserts both the
+  // agreement and the one case that parts them.
+  const expectancy = tally.tradeCount === 0 ? 0 : tally.netProfit / tally.tradeCount;
+
+  return {
+    capital,
+    currency: contract.currency,
+    netProfit: tally.netProfit,
+    grossProfit: tally.grossProfit,
+    grossLoss: tally.grossLoss,
+    charges: tally.charges,
+    returnPercent: ratioOf(tally.netProfit, capital),
+    tradeCount: tally.tradeCount,
+    openTradeCount: tally.openTradeCount,
+    wins: tally.wins,
+    losses: tally.losses,
+    scratches: tally.scratches,
+    winRate: decided === 0 ? null : tally.wins / decided,
+    averageWin: tally.wins === 0 ? 0 : tally.winTotal / tally.wins,
+    averageLoss: tally.losses === 0 ? 0 : -tally.lossTotal / tally.losses,
+    expectancy,
+    expectancyStandardError: standardErrorOf(trades, expectancy, tally.tradeCount),
+    profitFactor: tally.grossLoss > 0 ? tally.grossProfit / tally.grossLoss : null,
+    maxDrawdown: depth.maxDrawdown,
+    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,
+  };
+}
+
+/**
+ * One pass over the trades, in the order they are given.
+ *
+ * A trade wins or loses on its net after charges, and its gross is what it
+ * contributes to the gross figures: "the sum of the winning trades, before
+ * charges" is two statements and this is where they meet. The one arrangement
+ * that reads oddly is a trade whose gross was positive and whose charges took
+ * it under, which lands in the losses and takes its positive gross with it,
+ * lowering the gross loss. That is on purpose. The alternative is a trade
+ * counted as a loser in one figure and a winner in another, and a profit factor
+ * whose two halves are counted over different sets is worse than one whose
+ * magnitude is odd on a trade that barely moved.
+ *
+ * What is not on purpose, and is why `profitFactor` is null rather than a ratio
+ * whenever this figure is not above zero: enough of those trades and the gross
+ * loss reaches zero or goes under, and dividing by it reported a profit factor
+ * of minus a half. A statistic being odd is a thing a reader can weigh. A
+ * statistic being negative where every use of it is a non-negative ratio is a
+ * number nobody can act on.
+ */
+function tallyOf(trades: readonly Trade[]): Tally {
+  let netProfit = 0;
+  let grossProfit = 0;
+  let grossLoss = 0;
+  let charges = 0;
+  let tradeCount = 0;
+  let openTradeCount = 0;
+  let wins = 0;
+  let losses = 0;
+  let scratches = 0;
+  let winTotal = 0;
+  let lossTotal = 0;
+  let heldTotal = 0;
+  let heldCount = 0;
+
+  for (const trade of trades) {
+    charges += trade.charges;
+    if (trade.isOpen) {
+      openTradeCount += 1;
+      continue;
+    }
+    tradeCount += 1;
+    netProfit += trade.netProfit;
+    if (trade.barsHeld !== null) {
+      heldTotal += trade.barsHeld;
+      heldCount += 1;
+    }
+    if (trade.netProfit > 0) {
+      wins += 1;
+      winTotal += trade.netProfit;
+      grossProfit += trade.grossProfit;
+    } else if (trade.netProfit < 0) {
+      losses += 1;
+      lossTotal += trade.netProfit;
+      grossLoss -= trade.grossProfit;
+    } else {
+      scratches += 1;
+    }
+  }
+
+  return {
+    netProfit,
+    grossProfit,
+    grossLoss,
+    charges,
+    tradeCount,
+    openTradeCount,
+    wins,
+    losses,
+    scratches,
+    winTotal,
+    lossTotal,
+    heldTotal,
+    heldCount,
+  };
+}
+
+/**
+ * The deepest the curve went, named as one point rather than as three figures.
+ *
+ * The money, the fraction and the time all come from the same point, and the
+ * point is the deepest in money with the earliest one winning a tie. Taking the
+ * worst fraction from one bar and the worst money from another would describe a
+ * moment the run never had, and a reader comparing the two figures would find
+ * them inconsistent with every point in the curve they were drawn from.
+ *
+ * `longestDrawdownBars` is the longest run of consecutive bars under a peak: it
+ * starts at the first bar below one and ends at the bar before the recovery, so
+ * a run still under water at the last bar counts to the end. It is often the
+ * figure that actually stops a trader, and it is not the total number of bars
+ * spent under water, which is a different and much larger number.
+ */
+function depthOf(equity: readonly EquityPoint[]): Depth {
+  let maxDrawdown = 0;
+  let maxDrawdownPercent = 0;
+  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) {
+      maxDrawdown = point.drawdown;
+      maxDrawdownPercent = point.drawdownPercent;
+      maxDrawdownAt = point.time;
+    }
+    if (point.drawdown < 0) {
+      under += 1;
+      if (under > longestDrawdownBars) longestDrawdownBars = under;
+    } 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,
+    maxRunUp,
+    maxRunUpPercent,
+    maxRunUpAt,
+  };
+}
+
+/**
+ * The standard error of the expectancy: the sample deviation over the root of
+ * the count.
+ *
+ * The sample deviation, with the count less one under it, and not the
+ * population one. The trades a run took are a sample of the trades the strategy
+ * would take, which is the whole reason this figure is here, and the population
+ * spelling understates the spread by exactly the amount that matters on the
+ * short runs where the question is asked.
+ *
+ * Fewer than two closed trades has no spread to measure and gives zero.
+ */
+function standardErrorOf(
+  trades: readonly Trade[],
+  expectancy: Money,
+  tradeCount: number,
+): Money {
+  if (tradeCount < 2) return 0;
+
+  let squares = 0;
+  for (const trade of trades) {
+    if (trade.isOpen) continue;
+    const away = trade.netProfit - expectancy;
+    squares += away * away;
+  }
+  return Math.sqrt(squares / (tradeCount - 1) / tradeCount);
+}