orderflow-metrics 0.24.0

package/src/online.ts

@@ -0,0 +1,228 @@
+/**
+ * Online (streaming) estimators — O(1) per update, no rescans.
+ *
+ * Batch metrics recompute over the whole history every time a tick arrives;
+ * that is fine offline but wasteful in a live pipeline. The estimators here
+ * update in constant time and constant memory as each observation streams in,
+ * which is what you want feeding volatility or risk off a real-time tape.
+ *
+ * They are numerically careful: `Welford` and `RollingWindow` use Welford's
+ * and West's algorithms rather than the naive Σx² − (Σx)²/n form, which loses
+ * precision catastrophically when the mean is large relative to the variance.
+ *
+ *   Welford        — running mean & variance over all data seen so far
+ *   Ewma           — exponentially weighted moving average (a level)
+ *   EwmaVariance   — RiskMetrics-style EWMA variance (a volatility)
+ *   RollingWindow  — mean & variance over a fixed trailing window
+ *
+ * Sample variance uses the (n − 1) denominator; each class also exposes the
+ * population (n) form. Variance getters are floored at 0 to absorb the tiny
+ * negative values floating-point round-off can produce near zero.
+ */
+
+/**
+ * Streaming mean and variance over every value pushed so far, via Welford's
+ * online algorithm. Constant time and memory per update, and numerically
+ * stable regardless of the mean's magnitude.
+ */
+export class Welford {
+  #n = 0;
+  #mean = 0;
+  #m2 = 0;
+
+  /** Incorporate one observation. */
+  push(x: number): void {
+    this.#n += 1;
+    const delta = x - this.#mean;
+    this.#mean += delta / this.#n;
+    this.#m2 += delta * (x - this.#mean);
+  }
+
+  /** Number of observations seen. */
+  get count(): number {
+    return this.#n;
+  }
+
+  /** Running mean (0 before any observation). */
+  get mean(): number {
+    return this.#n > 0 ? this.#mean : 0;
+  }
+
+  /** Sample variance, (n − 1) denominator (0 for fewer than two observations). */
+  get variance(): number {
+    if (this.#n < 2) return 0;
+    const v = this.#m2 / (this.#n - 1);
+    return v > 0 ? v : 0;
+  }
+
+  /** Population variance, n denominator (0 before any observation). */
+  get populationVariance(): number {
+    if (this.#n < 1) return 0;
+    const v = this.#m2 / this.#n;
+    return v > 0 ? v : 0;
+  }
+
+  /** Sample standard deviation. */
+  get std(): number {
+    return Math.sqrt(this.variance);
+  }
+}
+
+/**
+ * Exponentially weighted moving average of a level: vₜ = λ·vₜ₋₁ + (1 − λ)·xₜ.
+ * `lambda` is the weight on history (decay), in (0, 1) — larger is smoother and
+ * slower to react. Seeded with the first value pushed.
+ */
+export class Ewma {
+  readonly #lambda: number;
+  #value = 0;
+  #init = false;
+
+  constructor(lambda: number) {
+    if (!(lambda > 0 && lambda < 1)) {
+      throw new RangeError("lambda must be in the open interval (0, 1)");
+    }
+    this.#lambda = lambda;
+  }
+
+  /** Incorporate one observation. */
+  push(x: number): void {
+    this.#value = this.#init ? this.#lambda * this.#value + (1 - this.#lambda) * x : x;
+    this.#init = true;
+  }
+
+  /** Current EWMA level (0 before any observation). */
+  get value(): number {
+    return this.#value;
+  }
+
+  /** Whether at least one value has been pushed. */
+  get initialized(): boolean {
+    return this.#init;
+  }
+}
+
+/**
+ * RiskMetrics-style exponentially weighted variance of a return series:
+ * σ²ₜ = λ·σ²ₜ₋₁ + (1 − λ)·r²ₜ. Assumes approximately zero-mean returns (the
+ * standard RiskMetrics assumption). `lambda` in (0, 1) is the decay; RiskMetrics
+ * uses 0.94 for daily data. Seeded with r² of the first value pushed.
+ */
+export class EwmaVariance {
+  readonly #lambda: number;
+  #var = 0;
+  #init = false;
+
+  constructor(lambda: number) {
+    if (!(lambda > 0 && lambda < 1)) {
+      throw new RangeError("lambda must be in the open interval (0, 1)");
+    }
+    this.#lambda = lambda;
+  }
+
+  /** Incorporate one return. */
+  push(r: number): void {
+    this.#var = this.#init ? this.#lambda * this.#var + (1 - this.#lambda) * r * r : r * r;
+    this.#init = true;
+  }
+
+  /** Current EWMA variance (0 before any observation). */
+  get variance(): number {
+    return this.#var;
+  }
+
+  /** Current EWMA volatility (standard deviation). */
+  get std(): number {
+    return Math.sqrt(this.#var);
+  }
+
+  /** Whether at least one value has been pushed. */
+  get initialized(): boolean {
+    return this.#init;
+  }
+}
+
+/**
+ * Mean and variance over a fixed trailing window of the last `size` values.
+ * Each push is O(1): the incoming value is added and, once the window is full,
+ * the oldest is removed, both via West's (1979) incremental update — so there is
+ * no per-tick rescan and no Σx² cancellation.
+ */
+export class RollingWindow {
+  readonly #size: number;
+  readonly #buf: number[] = [];
+  #idx = 0;
+  #n = 0;
+  #mean = 0;
+  #m2 = 0;
+
+  constructor(size: number) {
+    if (!Number.isInteger(size) || size < 1) {
+      throw new RangeError("size must be a positive integer");
+    }
+    this.#size = size;
+  }
+
+  /** Push one value, evicting the oldest once the window is full. */
+  push(x: number): void {
+    if (this.#n < this.#size) {
+      // Window not yet full: plain Welford add.
+      this.#n += 1;
+      const delta = x - this.#mean;
+      this.#mean += delta / this.#n;
+      this.#m2 += delta * (x - this.#mean);
+      this.#buf.push(x);
+      return;
+    }
+    // Full: add the newcomer, then remove the oldest (West's add + remove).
+    const old = this.#buf[this.#idx];
+    const n1 = this.#n + 1;
+    const delta = x - this.#mean;
+    const mean1 = this.#mean + delta / n1;
+    const m2Added = this.#m2 + delta * (x - mean1);
+    const mean0 = (n1 * mean1 - old) / this.#size;
+    this.#m2 = m2Added - (old - mean0) * (old - mean1);
+    this.#mean = mean0;
+    this.#buf[this.#idx] = x;
+    this.#idx = (this.#idx + 1) % this.#size;
+  }
+
+  /** Configured window size. */
+  get size(): number {
+    return this.#size;
+  }
+
+  /** Number of values currently in the window (≤ size). */
+  get count(): number {
+    return this.#n;
+  }
+
+  /** Whether the window has filled to `size`. */
+  get full(): boolean {
+    return this.#n === this.#size;
+  }
+
+  /** Mean of the current window (0 when empty). */
+  get mean(): number {
+    return this.#n > 0 ? this.#mean : 0;
+  }
+
+  /** Sample variance of the current window (0 for fewer than two values). */
+  get variance(): number {
+    if (this.#n < 2) return 0;
+    const v = this.#m2 / (this.#n - 1);
+    return v > 0 ? v : 0;
+  }
+
+  /** Population variance of the current window (0 when empty). */
+  get populationVariance(): number {
+    if (this.#n < 1) return 0;
+    const v = this.#m2 / this.#n;
+    return v > 0 ? v : 0;
+  }
+
+  /** Sample standard deviation of the current window. */
+  get std(): number {
+    return Math.sqrt(this.variance);
+  }
+}

package/src/orderbook.ts

@@ -0,0 +1,76 @@
+/**
+ * Limit order book reconstruction from incremental level updates.
+ *
+ * Feed it level updates (price + new size per side); it maintains both sides
+ * and answers the usual top-of-book and depth questions. A size of 0 removes
+ * the level. Prices are the level keys, so re-sending a price overwrites it.
+ */
+
+export type BookSide = "bid" | "ask";
+
+export interface Level {
+  price: number;
+  size: number;
+}
+
+export class OrderBook {
+  private readonly bids = new Map<number, number>();
+  private readonly asks = new Map<number, number>();
+
+  /** Apply a level update. ``size <= 0`` removes the price level. */
+  update(side: BookSide, price: number, size: number): void {
+    const book = side === "bid" ? this.bids : this.asks;
+    if (size <= 0) book.delete(price);
+    else book.set(price, size);
+  }
+
+  bestBid(): Level | null {
+    let best: Level | null = null;
+    for (const [price, size] of this.bids) {
+      if (best === null || price > best.price) best = { price, size };
+    }
+    return best;
+  }
+
+  bestAsk(): Level | null {
+    let best: Level | null = null;
+    for (const [price, size] of this.asks) {
+      if (best === null || price < best.price) best = { price, size };
+    }
+    return best;
+  }
+
+  mid(): number | null {
+    const b = this.bestBid();
+    const a = this.bestAsk();
+    return b && a ? (b.price + a.price) / 2 : null;
+  }
+
+  spread(): number | null {
+    const b = this.bestBid();
+    const a = this.bestAsk();
+    return b && a ? a.price - b.price : null;
+  }
+
+  /** Top ``n`` levels of a side, best price first. */
+  depth(side: BookSide, n: number): Level[] {
+    const book = side === "bid" ? this.bids : this.asks;
+    const levels: Level[] = [...book.entries()].map(([price, size]) => ({
+      price,
+      size,
+    }));
+    levels.sort((x, y) => (side === "bid" ? y.price - x.price : x.price - y.price));
+    return levels.slice(0, n);
+  }
+
+  /**
+   * Book imbalance over the top ``n`` levels:
+   * (bidVolume − askVolume) / (bidVolume + askVolume), in [-1, 1].
+   */
+  imbalance(n = 1): number {
+    const bidVol = this.depth("bid", n).reduce((s, l) => s + l.size, 0);
+    const askVol = this.depth("ask", n).reduce((s, l) => s + l.size, 0);
+    const denom = bidVol + askVol;
+    return denom === 0 ? 0 : (bidVol - askVol) / denom;
+  }
+}

package/src/rangevol.ts

@@ -0,0 +1,108 @@
+/**
+ * Range-based volatility estimators from OHLC candles.
+ *
+ * Close-to-close realized volatility (see `volatility`) throws away most of each
+ * bar — it reads only the close. But the open, high, and low carry information
+ * too, and using them yields far more efficient volatility estimates from the
+ * same data. Four classic estimators, in increasing order of what they use:
+ *
+ *  - Parkinson (1980): the high-low range only.
+ *  - Garman-Klass (1980): adds the open and close.
+ *  - Rogers-Satchell (1991): drift-independent (correct under a trending mean).
+ *  - Yang-Zhang (2000): drift-independent and robust to overnight jumps.
+ *
+ * Each returns the estimated volatility (standard deviation) *per bar*. To
+ * annualize, multiply the variance by the number of bars per year, or the
+ * volatility by its square root. Prices must be strictly positive.
+ */
+
+export interface Candle {
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+}
+
+const LN2 = Math.LN2;
+
+/** Parkinson (1980) high-low volatility. Returns 0 for an empty input. */
+export function parkinsonVolatility(bars: Candle[]): number {
+  const n = bars.length;
+  if (n === 0) return 0;
+  let s = 0;
+  for (const b of bars) {
+    const hl = Math.log(b.high / b.low);
+    s += hl * hl;
+  }
+  return Math.sqrt(s / (4 * LN2) / n);
+}
+
+/** Garman-Klass (1980) OHLC volatility. Returns 0 for an empty input. */
+export function garmanKlassVolatility(bars: Candle[]): number {
+  const n = bars.length;
+  if (n === 0) return 0;
+  let s = 0;
+  for (const b of bars) {
+    const hl = Math.log(b.high / b.low);
+    const co = Math.log(b.close / b.open);
+    s += 0.5 * hl * hl - (2 * LN2 - 1) * co * co;
+  }
+  const v = s / n;
+  return v > 0 ? Math.sqrt(v) : 0;
+}
+
+/**
+ * Rogers-Satchell (1991) drift-independent OHLC volatility. Correct even when
+ * the price has a non-zero mean drift. Returns 0 for an empty input.
+ */
+export function rogersSatchellVolatility(bars: Candle[]): number {
+  const n = bars.length;
+  if (n === 0) return 0;
+  let s = 0;
+  for (const b of bars) {
+    s +=
+      Math.log(b.high / b.close) * Math.log(b.high / b.open) +
+      Math.log(b.low / b.close) * Math.log(b.low / b.open);
+  }
+  const v = s / n;
+  return v > 0 ? Math.sqrt(v) : 0;
+}
+
+/**
+ * Yang-Zhang (2000) volatility: a minimum-variance combination of overnight,
+ * open-to-close, and Rogers-Satchell variances that is both drift-independent
+ * and robust to opening jumps. Uses each bar's open relative to the previous
+ * close, so it needs at least three bars; returns 0 otherwise.
+ */
+export function yangZhangVolatility(bars: Candle[]): number {
+  const n = bars.length;
+  if (n < 3) return 0;
+  const overnight: number[] = [];
+  const openClose: number[] = [];
+  let rs = 0;
+  for (let i = 1; i < n; i++) {
+    const prev = bars[i - 1];
+    const b = bars[i];
+    overnight.push(Math.log(b.open / prev.close));
+    openClose.push(Math.log(b.close / b.open));
+    rs +=
+      Math.log(b.high / b.close) * Math.log(b.high / b.open) +
+      Math.log(b.low / b.close) * Math.log(b.low / b.open);
+  }
+  const m = overnight.length;
+  const mean = (a: number[]) => a.reduce((x, y) => x + y, 0) / a.length;
+  const ob = mean(overnight);
+  const cb = mean(openClose);
+  let so = 0;
+  let sc = 0;
+  for (let i = 0; i < m; i++) {
+    so += (overnight[i] - ob) ** 2;
+    sc += (openClose[i] - cb) ** 2;
+  }
+  so /= m - 1;
+  sc /= m - 1;
+  const rsv = rs / m;
+  const k = 0.34 / (1.34 + (m + 1) / (m - 1));
+  const v = so + k * sc + (1 - k) * rsv;
+  return v > 0 ? Math.sqrt(v) : 0;
+}

package/src/scheduling.ts

@@ -0,0 +1,50 @@
+/**
+ * Execution scheduling: split a parent order into child slices.
+ *
+ * `twap` spreads size evenly across a fixed number of slices (time-weighted).
+ * `pov` participates at a fixed fraction of each interval's volume
+ * (percentage-of-volume). Both return the child sizes; sizes may be fractional.
+ */
+
+/**
+ * TWAP: split ``totalSize`` into ``slices`` equal child orders. The sizes sum
+ * exactly to ``totalSize`` (any floating residual lands in the last slice).
+ */
+export function twap(totalSize: number, slices: number): number[] {
+  if (slices < 1 || !Number.isInteger(slices)) {
+    throw new Error("slices must be a positive integer");
+  }
+  const out: number[] = [];
+  let allocated = 0;
+  for (let i = 1; i <= slices; i++) {
+    const target = (totalSize * i) / slices;
+    out.push(target - allocated);
+    allocated = target;
+  }
+  return out;
+}
+
+/**
+ * POV: for each interval, trade ``rate`` × that interval's volume, capped by
+ * the size still remaining. Returns per-interval child sizes; their sum is the
+ * filled amount (less than ``totalSize`` if the volume was insufficient).
+ */
+export function pov(
+  totalSize: number,
+  intervalVolumes: readonly number[],
+  rate: number,
+): number[] {
+  const r = Math.max(0, rate);
+  const out: number[] = [];
+  let remaining = totalSize;
+  for (const vol of intervalVolumes) {
+    if (remaining <= 0) {
+      out.push(0);
+      continue;
+    }
+    const child = Math.min(remaining, r * Math.max(0, vol));
+    out.push(child);
+    remaining -= child;
+  }
+  return out;
+}

package/src/semivar.ts

@@ -0,0 +1,67 @@
+/**
+ * Realized semivariance and signed jump variation
+ * (Barndorff-Nielsen, Kinnebrock & Shephard, 2010; Patton & Shephard, 2015).
+ *
+ * Realized variance (RV = Σ rᵢ²) treats an up-move and a down-move of equal
+ * size as identical risk. But most traders care far more about the downside.
+ * Realized semivariance splits RV by the *sign* of each return:
+ *
+ *   RS⁺ = Σ rᵢ² · 1{rᵢ > 0}   (upside)
+ *   RS⁻ = Σ rᵢ² · 1{rᵢ < 0}   (downside)
+ *   RS⁺ + RS⁻ = RV            (zero returns contribute to neither)
+ *
+ * The two halves carry different information: RS⁻ (bad volatility) is the part
+ * that predicts future risk and demands a premium, while RS⁺ (good volatility)
+ * behaves quite differently. Their difference is the *signed* jump variation,
+ * which — unlike ordinary jump variation — keeps the direction of jump risk:
+ *
+ *   signed jump variation = RS⁺ − RS⁻
+ *
+ * A positive value means upside moves dominate; a negative value means the
+ * series is downside-heavy. Each function takes a return series.
+ */
+
+/** Upside / downside decomposition of realized variance. Both are ≥ 0. */
+export interface Semivariance {
+  /** RS⁺ = Σ rᵢ² over strictly positive returns. */
+  upside: number;
+  /** RS⁻ = Σ rᵢ² over strictly negative returns. */
+  downside: number;
+}
+
+/**
+ * Realized semivariance: splits realized variance into the sum of squared
+ * positive returns (upside) and squared negative returns (downside). Zero
+ * returns are ignored, so `upside + downside` equals realized variance. An
+ * empty series returns { upside: 0, downside: 0 }.
+ */
+export function realizedSemivariance(returns: readonly number[]): Semivariance {
+  let upside = 0;
+  let downside = 0;
+  for (const r of returns) {
+    if (r > 0) upside += r * r;
+    else if (r < 0) downside += r * r;
+  }
+  return { upside, downside };
+}
+
+/**
+ * Downside variance ratio: RS⁻ / (RS⁺ + RS⁻), the share of realized variance
+ * coming from negative returns, in [0, 1]. Returns 0 when realized variance is
+ * 0 (or the series is empty). A value above 0.5 marks a downside-heavy window.
+ */
+export function downsideVarianceRatio(returns: readonly number[]): number {
+  const { upside, downside } = realizedSemivariance(returns);
+  const total = upside + downside;
+  return total > 0 ? downside / total : 0;
+}
+
+/**
+ * Signed jump variation: RS⁺ − RS⁻ (Patton & Shephard, 2015). Positive when
+ * upside moves dominate, negative when downside moves dominate; unlike jump
+ * variation it can take either sign. Returns 0 for an empty series.
+ */
+export function signedJumpVariation(returns: readonly number[]): number {
+  const { upside, downside } = realizedSemivariance(returns);
+  return upside - downside;
+}

package/src/shortfall.ts

@@ -0,0 +1,69 @@
+/**
+ * Implementation shortfall and arrival slippage.
+ *
+ * Perold's (1988) "implementation shortfall" measures the all-in cost of turning
+ * a paper decision into real fills. It splits into the cost paid on the shares
+ * you actually executed (vs the price when you decided), the opportunity cost of
+ * the shares you failed to execute as the price drifted away, and fees. Arrival
+ * slippage is the simpler, per-order version against the arrival mid.
+ *
+ * Sign convention: buys are +1, sells are -1. All costs are returned as
+ * *positive = worse* (a shortfall), in the input price/quantity units.
+ */
+import type { Side } from "./types.ts";
+
+function dir(side: Side): 1 | -1 {
+  return side === "buy" ? 1 : -1;
+}
+
+export interface ShortfallResult {
+  /** Cost on executed shares vs the decision price. */
+  execution: number;
+  /** Opportunity cost of unexecuted shares as the price drifted. */
+  opportunity: number;
+  /** Explicit fees / commissions. */
+  fees: number;
+  /** execution + opportunity + fees. Positive = shortfall (cost). */
+  total: number;
+}
+
+/**
+ * Implementation shortfall of an order, decomposed into execution cost,
+ * opportunity cost, and fees.
+ *
+ * @param decisionPrice  price when the trade was decided (the paper benchmark)
+ * @param avgExecPrice   volume-weighted average price actually paid/received
+ * @param executedQty    shares actually filled
+ * @param targetQty      shares originally intended
+ * @param finalPrice     price at the end of trading (for the unfilled remainder)
+ * @param fees           explicit costs (default 0)
+ */
+export function implementationShortfall(
+  side: Side,
+  decisionPrice: number,
+  avgExecPrice: number,
+  executedQty: number,
+  targetQty: number,
+  finalPrice: number,
+  fees = 0,
+): ShortfallResult {
+  const d = dir(side);
+  const execution = d * (avgExecPrice - decisionPrice) * executedQty;
+  const unexecuted = Math.max(0, targetQty - executedQty);
+  const opportunity = d * (finalPrice - decisionPrice) * unexecuted;
+  return { execution, opportunity, fees, total: execution + opportunity + fees };
+}
+
+/**
+ * Arrival slippage in basis points: signed cost of the average execution price
+ * against the arrival price. Positive = adverse (paid up on a buy / sold low on
+ * a sell). Returns 0 when the arrival price is 0.
+ */
+export function arrivalSlippageBps(
+  side: Side,
+  arrivalPrice: number,
+  avgExecPrice: number,
+): number {
+  if (arrivalPrice === 0) return 0;
+  return ((dir(side) * (avgExecPrice - arrivalPrice)) / arrivalPrice) * 10_000;
+}

package/src/simulate.ts

@@ -0,0 +1,68 @@
+/**
+ * Market-order simulation against a reconstructed order book.
+ *
+ * Sweep the book with a market order and see what you'd actually get: the
+ * volume-weighted fill price, slippage vs the starting mid, and any size the
+ * book was too thin to fill. Read-only — the book is not mutated.
+ */
+import { OrderBook } from "./orderbook.ts";
+
+export interface Fill {
+  price: number;
+  size: number;
+}
+
+export interface MarketOrderResult {
+  filledSize: number;
+  remainingSize: number;
+  /** volume-weighted average fill price, or null if nothing filled */
+  avgPrice: number | null;
+  notional: number;
+  /** cost vs the mid at start, in basis points (positive = adverse); null if unknown */
+  slippageBps: number | null;
+  fills: Fill[];
+}
+
+/**
+ * Simulate a market order. A ``buy`` consumes asks from best (lowest) upward;
+ * a ``sell`` consumes bids from best (highest) downward. Stops when filled or
+ * the book runs out (``remainingSize`` > 0).
+ */
+export function simulateMarketOrder(
+  book: OrderBook,
+  side: "buy" | "sell",
+  size: number,
+): MarketOrderResult {
+  const startMid = book.mid();
+  const levels = book.depth(side === "buy" ? "ask" : "bid", Number.MAX_SAFE_INTEGER);
+
+  const fills: Fill[] = [];
+  let remaining = size;
+  let notional = 0;
+
+  for (const level of levels) {
+    if (remaining <= 0) break;
+    const take = Math.min(remaining, level.size);
+    fills.push({ price: level.price, size: take });
+    notional += level.price * take;
+    remaining -= take;
+  }
+
+  const filled = size - remaining;
+  const avgPrice = filled > 0 ? notional / filled : null;
+
+  let slippageBps: number | null = null;
+  if (avgPrice !== null && startMid !== null && startMid !== 0) {
+    const raw = side === "buy" ? avgPrice - startMid : startMid - avgPrice;
+    slippageBps = (raw / startMid) * 10_000;
+  }
+
+  return {
+    filledSize: filled,
+    remainingSize: remaining,
+    avgPrice,
+    notional,
+    slippageBps,
+    fills,
+  };
+}