orderflow-metrics 0.24.0

package/src/execution.ts

@@ -0,0 +1,100 @@
+/**
+ * Execution-cost and price-impact metrics.
+ *
+ * Standard transaction-cost analysis (TCA) building blocks:
+ *   - effective spread  — realized cost against the quote midpoint
+ *   - realized spread   — liquidity-provider revenue (post-trade reversion)
+ *   - price impact      — permanent component (effective − realized)
+ *   - Kyle's lambda      — price impact per unit of signed order flow
+ *   - Roll's estimator   — effective spread implied by price-change autocovariance
+ *
+ * Sign convention: buys are +1, sells are −1. All spread measures are in the
+ * same price units as the inputs.
+ */
+import type { Side } from "./types.ts";
+
+function dir(side: Side): 1 | -1 {
+  return side === "buy" ? 1 : -1;
+}
+
+/** Effective half-spread: d·(price − mid). */
+export function effectiveHalfSpread(
+  price: number,
+  mid: number,
+  side: Side,
+): number {
+  return dir(side) * (price - mid);
+}
+
+/** Effective (full) spread: 2·d·(price − mid). */
+export function effectiveSpread(price: number, mid: number, side: Side): number {
+  return 2 * effectiveHalfSpread(price, mid, side);
+}
+
+/** Realized (full) spread using the mid observed Δ later: 2·d·(price − midAfter). */
+export function realizedSpread(
+  price: number,
+  midAfter: number,
+  side: Side,
+): number {
+  return 2 * dir(side) * (price - midAfter);
+}
+
+/** Permanent price impact: 2·d·(midAfter − mid) = effectiveSpread − realizedSpread. */
+export function priceImpact(mid: number, midAfter: number, side: Side): number {
+  return 2 * dir(side) * (midAfter - mid);
+}
+
+export interface FlowObservation {
+  /** mid-price change over the interval */
+  priceChange: number;
+  /** signed traded volume (positive = net buy) */
+  signedVolume: number;
+}
+
+/**
+ * Kyle's lambda — OLS slope of price change on signed order flow
+ * (ΔP = λ · signedVolume + ε). Returns 0 for degenerate input.
+ */
+export function kyleLambda(obs: FlowObservation[]): number {
+  const n = obs.length;
+  if (n < 2) return 0;
+
+  let mx = 0;
+  let my = 0;
+  for (const o of obs) {
+    mx += o.signedVolume;
+    my += o.priceChange;
+  }
+  mx /= n;
+  my /= n;
+
+  let cov = 0;
+  let varx = 0;
+  for (const o of obs) {
+    const dx = o.signedVolume - mx;
+    cov += dx * (o.priceChange - my);
+    varx += dx * dx;
+  }
+  return varx === 0 ? 0 : cov / varx;
+}
+
+/**
+ * Roll's (1984) implied effective spread from a series of trade prices:
+ * 2·√(−cov(ΔP_t, ΔP_{t-1})). Returns 0 when the autocovariance is
+ * non-negative (the estimator is undefined there).
+ */
+export function rollSpread(prices: number[]): number {
+  if (prices.length < 3) return 0;
+
+  const dp: number[] = [];
+  for (let i = 1; i < prices.length; i++) dp.push(prices[i] - prices[i - 1]);
+
+  const n = dp.length;
+  const mean = dp.reduce((a, b) => a + b, 0) / n;
+  let cov = 0;
+  for (let i = 1; i < n; i++) cov += (dp[i] - mean) * (dp[i - 1] - mean);
+  cov /= n - 1;
+
+  return cov < 0 ? 2 * Math.sqrt(-cov) : 0;
+}

package/src/fairvalue.ts

@@ -0,0 +1,33 @@
+/**
+ * Fair-value and quoting helpers derived from the top of book.
+ */
+import type { L1Quote } from "./types.ts";
+
+/**
+ * Imbalance-weighted mid price (a simple micro-price).
+ *
+ *   weightedMid = bid · askSize/(bidSize+askSize) + ask · bidSize/(bidSize+askSize)
+ *
+ * Each side is weighted by the *opposite* size, so heavy resting bid size
+ * pulls the estimate toward the ask (upward pressure), and vice versa. Falls
+ * back to the arithmetic mid when both sizes are zero.
+ */
+export function weightedMid(q: L1Quote): number {
+  const total = q.bidSize + q.askSize;
+  if (total === 0) return (q.bidPrice + q.askPrice) / 2;
+  return (
+    q.bidPrice * (q.askSize / total) + q.askPrice * (q.bidSize / total)
+  );
+}
+
+/** Arithmetic mid price: (bid + ask) / 2. */
+export function mid(q: L1Quote): number {
+  return (q.bidPrice + q.askPrice) / 2;
+}
+
+/** Quoted spread in basis points: (ask − bid) / mid · 10_000. */
+export function relativeSpreadBps(q: L1Quote): number {
+  const m = mid(q);
+  if (m === 0) return 0;
+  return ((q.askPrice - q.bidPrice) / m) * 10_000;
+}

package/src/hurst.ts

@@ -0,0 +1,77 @@
+/**
+ * Hurst exponent via rescaled-range (R/S) analysis.
+ *
+ * The Hurst exponent H characterises the long-memory of a series:
+ *   - H ≈ 0.5 — no memory (white noise; the increments of a random walk)
+ *   - H > 0.5 — persistent / trending (moves tend to continue)
+ *   - H < 0.5 — anti-persistent / mean-reverting (moves tend to reverse)
+ *
+ * It is estimated from the classic rescaled range: over windows of growing
+ * size n, the average R/S statistic scales like n^H, so H is the slope of
+ * log(R/S) against log(n). A companion to the market-efficiency metrics
+ * (autocorrelation, variance ratio).
+ *
+ * Feed it a roughly stationary series — typically returns, not raw prices.
+ * Returns NaN when the series is too short to form at least two window scales
+ * (with the default minimum window, that means fewer than ~32 points).
+ */
+
+export interface HurstOptions {
+  /** Smallest window size for the R/S regression (default 8). */
+  minWindow?: number;
+}
+
+export function hurstExponent(
+  series: readonly number[],
+  opts: HurstOptions = {},
+): number {
+  const minWindow = opts.minWindow ?? 8;
+  const N = series.length;
+  const scales: number[] = [];
+  const rsMeans: number[] = [];
+
+  for (let n = minWindow; n <= Math.floor(N / 2); n *= 2) {
+    const k = Math.floor(N / n);
+    const rsVals: number[] = [];
+    for (let j = 0; j < k; j++) {
+      const start = j * n;
+      let mean = 0;
+      for (let i = 0; i < n; i++) mean += series[start + i];
+      mean /= n;
+      let cum = 0;
+      let min = Infinity;
+      let max = -Infinity;
+      let sumSq = 0;
+      for (let i = 0; i < n; i++) {
+        const d = series[start + i] - mean;
+        cum += d;
+        if (cum < min) min = cum;
+        if (cum > max) max = cum;
+        sumSq += d * d;
+      }
+      const range = max - min;
+      const stdev = Math.sqrt(sumSq / n);
+      if (stdev > 0) rsVals.push(range / stdev);
+    }
+    if (rsVals.length > 0) {
+      scales.push(n);
+      rsMeans.push(rsVals.reduce((a, b) => a + b, 0) / rsVals.length);
+    }
+  }
+
+  if (scales.length < 2) return NaN;
+
+  // Hurst exponent = slope of log(R/S) vs log(n).
+  const xs = scales.map((s) => Math.log(s));
+  const ys = rsMeans.map((r) => Math.log(r));
+  const m = xs.length;
+  const mx = xs.reduce((a, b) => a + b, 0) / m;
+  const my = ys.reduce((a, b) => a + b, 0) / m;
+  let num = 0;
+  let den = 0;
+  for (let i = 0; i < m; i++) {
+    num += (xs[i] - mx) * (ys[i] - my);
+    den += (xs[i] - mx) ** 2;
+  }
+  return num / den;
+}

package/src/imbalance.ts

@@ -0,0 +1,25 @@
+/**
+ * Book and trade imbalance metrics.
+ *
+ * Both return a value in [-1, 1]: positive = buy-side heavy, negative =
+ * sell-side heavy, 0 = balanced (or empty input).
+ */
+import type { L1Quote, Trade } from "./types.ts";
+
+/** Top-of-book depth imbalance: (bidSize − askSize) / (bidSize + askSize). */
+export function depthImbalance(q: L1Quote): number {
+  const denom = q.bidSize + q.askSize;
+  return denom === 0 ? 0 : (q.bidSize - q.askSize) / denom;
+}
+
+/** Trade imbalance: (buyVolume − sellVolume) / (buyVolume + sellVolume). */
+export function tradeImbalance(trades: Trade[]): number {
+  let buy = 0;
+  let sell = 0;
+  for (const t of trades) {
+    if (t.side === "buy") buy += t.size;
+    else sell += t.size;
+  }
+  const denom = buy + sell;
+  return denom === 0 ? 0 : (buy - sell) / denom;
+}

package/src/impact.ts

@@ -0,0 +1,99 @@
+/**
+ * Market-impact models and trade markouts.
+ *
+ * Two pre-trade cost models — the empirical square-root law and the linear
+ * Almgren-Chriss temporary/permanent decomposition — plus post-trade markouts,
+ * the realized adverse-selection drift after a fill. Together they cover the
+ * "what will it cost / what did it cost" pair around execution.
+ *
+ * Sign convention for markouts: buys are +1, sells are -1.
+ */
+import type { Side } from "./types.ts";
+
+function dir(side: Side): 1 | -1 {
+  return side === "buy" ? 1 : -1;
+}
+
+/**
+ * Square-root law of market impact: `coefficient * sigma * sqrt(Q / V)`.
+ *
+ * The widely-observed empirical scaling of impact with participation: cost
+ * grows with volatility `sigma` and the square root of the order size `Q`
+ * relative to market volume `V`. `coefficient` (Y, typically ~0.5-1) absorbs
+ * the asset/venue-specific constant. Returns a dimensionless cost fraction, or
+ * 0 for non-positive volume or size.
+ */
+export function squareRootImpact(
+  sigma: number,
+  orderSize: number,
+  marketVolume: number,
+  coefficient = 1,
+): number {
+  if (!(marketVolume > 0) || orderSize <= 0) return 0;
+  return coefficient * sigma * Math.sqrt(orderSize / marketVolume);
+}
+
+/** Linear permanent impact: the lasting price shift `gamma * quantity`. */
+export function linearPermanentImpact(gamma: number, quantity: number): number {
+  return gamma * quantity;
+}
+
+/** Linear temporary impact at trading rate `rate`: `eta * rate`. */
+export function linearTemporaryImpact(eta: number, rate: number): number {
+  return eta * rate;
+}
+
+/** Expected impact cost of a schedule, split into its two components. */
+export interface ImpactCost {
+  permanent: number;
+  temporary: number;
+  total: number;
+}
+
+/**
+ * Almgren-Chriss expected impact cost of a uniform (TWAP) liquidation of
+ * `quantity` over `duration`, under linear temporary (`eta`) and permanent
+ * (`gamma`) impact:
+ *
+ *   permanent = 0.5 * gamma * Q^2      (paid on average over the trade)
+ *   temporary = eta * Q^2 / T          (uniform rate Q/T over T)
+ *
+ * `duration` must be positive.
+ */
+export function almgrenChrissCost(
+  quantity: number,
+  duration: number,
+  eta: number,
+  gamma: number,
+): ImpactCost {
+  if (!(duration > 0)) throw new Error("duration must be positive");
+  const permanent = 0.5 * gamma * quantity * quantity;
+  const temporary = (eta * quantity * quantity) / duration;
+  return { permanent, temporary, total: permanent + temporary };
+}
+
+/**
+ * Signed post-trade markout: `d * (midAfter - midAtTrade)`.
+ *
+ * How far the mid moved in the aggressor's favour over some horizon after the
+ * fill. Positive = the trade "looked informed" (price kept going its way);
+ * negative = it faded. This is the liquidity taker's realized edge and the
+ * provider's adverse selection, with the sign flipped.
+ */
+export function markout(side: Side, midAtTrade: number, midAfter: number): number {
+  return dir(side) * (midAfter - midAtTrade);
+}
+
+export interface MarkoutObservation {
+  side: Side;
+  midAtTrade: number;
+  midAfter: number;
+}
+
+/** Average markout across observations (0 for an empty set). */
+export function averageMarkout(obs: readonly MarkoutObservation[]): number {
+  if (obs.length === 0) return 0;
+  let s = 0;
+  for (const o of obs) s += markout(o.side, o.midAtTrade, o.midAfter);
+  return s / obs.length;
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+export type { L1Quote, Trade, Side } from "./types.ts";
+export { ofi, ofiSeries, ofiContribution } from "./ofi.ts";
+export { depthImbalance, tradeImbalance } from "./imbalance.ts";
+export type { VolumeBucket } from "./vpin.ts";
+export {
+  vpin,
+  bucketByVolume,
+  bvcBuyFraction,
+  standardNormalCdf,
+} from "./vpin.ts";
+export type { FlowObservation } from "./execution.ts";
+export {
+  effectiveSpread,
+  effectiveHalfSpread,
+  realizedSpread,
+  priceImpact,
+  kyleLambda,
+  rollSpread,
+} from "./execution.ts";
+export { mid, weightedMid, relativeSpreadBps } from "./fairvalue.ts";
+export type { Sign, PriceVsMid } from "./classify.ts";
+export { tickRule, leeReady } from "./classify.ts";
+export type { ReturnVolume } from "./liquidity.ts";
+export { amihudIlliquidity } from "./liquidity.ts";
+export {
+  realizedVariance,
+  realizedVolatility,
+  annualizedVolatility,
+} from "./volatility.ts";
+export { autocorrelation, varianceRatio } from "./efficiency.ts";
+export type { BookSide, Level } from "./orderbook.ts";
+export { OrderBook } from "./orderbook.ts";
+export type { Fill, MarketOrderResult } from "./simulate.ts";
+export { simulateMarketOrder } from "./simulate.ts";
+export { twap, pov } from "./scheduling.ts";
+export type { Bar } from "./bars.ts";
+export { tickBars, volumeBars, dollarBars } from "./bars.ts";
+export type { ImpactCost, MarkoutObservation } from "./impact.ts";
+export {
+  squareRootImpact,
+  linearPermanentImpact,
+  linearTemporaryImpact,
+  almgrenChrissCost,
+  markout,
+  averageMarkout,
+} from "./impact.ts";
+export type { ShortfallResult } from "./shortfall.ts";
+export { implementationShortfall, arrivalSlippageBps } from "./shortfall.ts";
+export type { Ohlc } from "./spreadest.ts";
+export { corwinSchultz, abdiRanaldo } from "./spreadest.ts";
+export type { Candle } from "./rangevol.ts";
+export {
+  parkinsonVolatility,
+  garmanKlassVolatility,
+  rogersSatchellVolatility,
+  yangZhangVolatility,
+} from "./rangevol.ts";
+export type { HurstOptions } from "./hurst.ts";
+export { hurstExponent } from "./hurst.ts";
+export { realizedSkewness, realizedKurtosis } from "./moments.ts";
+export {
+  bipowerVariation,
+  jumpVariation,
+  relativeJumpVariation,
+} from "./jumps.ts";
+export type { Semivariance } from "./semivar.ts";
+export {
+  realizedSemivariance,
+  downsideVarianceRatio,
+  signedJumpVariation,
+} from "./semivar.ts";
+export {
+  shannonEntropy,
+  normalizedEntropy,
+  signEntropy,
+} from "./entropy.ts";
+export {
+  Welford,
+  Ewma,
+  EwmaVariance,
+  RollingWindow,
+} from "./online.ts";
+export {
+  realizedCovariance,
+  realizedCorrelation,
+  realizedBeta,
+} from "./covariance.ts";

package/src/jumps.ts

@@ -0,0 +1,61 @@
+/**
+ * Jump detection via bipower variation (Barndorff-Nielsen & Shephard, 2004/2006).
+ *
+ * Realized variance (RV = Σ rᵢ²) mixes two very different kinds of risk: the
+ * continuous diffusion of price, and discrete jumps. Bipower variation (BV)
+ * estimates only the *continuous* part — multiplying adjacent absolute returns
+ * is robust to a lone large jump (a jump inflates one return but is paired with
+ * a small neighbour). The difference RV − BV isolates the jump contribution.
+ *
+ *   BV = (π/2) · Σᵢ |rᵢ₋₁| · |rᵢ|
+ *   jump variation = max(RV − BV, 0)
+ *
+ * Each function takes a return series and returns a non-negative number; the
+ * relative jump is the share of realized variance attributable to jumps, in
+ * [0, 1].
+ */
+
+// 1 / μ₁² where μ₁ = E[|Z|] = √(2/π) for Z ~ N(0,1); 1/μ₁² = π/2.
+const MU1_INV_SQ = Math.PI / 2;
+
+/** Realized variance Σ rᵢ² (local helper). */
+function realizedVar(returns: readonly number[]): number {
+  let s = 0;
+  for (const r of returns) s += r * r;
+  return s;
+}
+
+/**
+ * Bipower variation: (π/2) · Σ |rᵢ₋₁||rᵢ|. A jump-robust estimate of the
+ * continuous (diffusive) part of realized variance. Returns 0 for fewer than
+ * two returns.
+ */
+export function bipowerVariation(returns: readonly number[]): number {
+  const n = returns.length;
+  if (n < 2) return 0;
+  let s = 0;
+  for (let i = 1; i < n; i++) s += Math.abs(returns[i - 1]) * Math.abs(returns[i]);
+  return MU1_INV_SQ * s;
+}
+
+/**
+ * Jump variation: max(RV − BV, 0), the part of realized variance attributable
+ * to discrete jumps. Returns 0 for fewer than two returns.
+ */
+export function jumpVariation(returns: readonly number[]): number {
+  if (returns.length < 2) return 0;
+  const j = realizedVar(returns) - bipowerVariation(returns);
+  return j > 0 ? j : 0;
+}
+
+/**
+ * Relative jump: jump variation as a share of realized variance, in [0, 1].
+ * Returns 0 when realized variance is 0 or there are fewer than two returns.
+ */
+export function relativeJumpVariation(returns: readonly number[]): number {
+  if (returns.length < 2) return 0;
+  const total = realizedVar(returns);
+  if (total === 0) return 0;
+  const j = total - bipowerVariation(returns);
+  return j > 0 ? j / total : 0;
+}

package/src/liquidity.ts

@@ -0,0 +1,29 @@
+/**
+ * Liquidity measures.
+ */
+
+export interface ReturnVolume {
+  /** period return (e.g. close-to-close), as a fraction */
+  ret: number;
+  /** traded volume (or dollar volume) over the same period */
+  volume: number;
+}
+
+/**
+ * Amihud (2002) illiquidity: the average of |return| / volume across periods.
+ *
+ * It captures how much price moves per unit of volume — a high value means
+ * even small trades push the price a lot (thin, illiquid). Periods with zero
+ * volume are skipped. Returns 0 when there is no usable data.
+ */
+export function amihudIlliquidity(obs: readonly ReturnVolume[]): number {
+  let sum = 0;
+  let n = 0;
+  for (const o of obs) {
+    if (o.volume > 0) {
+      sum += Math.abs(o.ret) / o.volume;
+      n += 1;
+    }
+  }
+  return n === 0 ? 0 : sum / n;
+}

package/src/moments.ts

@@ -0,0 +1,45 @@
+/**
+ * Realized higher moments from an intraday return series.
+ *
+ * Following Amaya, Christoffersen, Jacobs & Vasquez (2015), the realized
+ * skewness and kurtosis of a set of high-frequency returns summarise the shape
+ * of the intraday return distribution — asymmetry and tail heaviness — beyond
+ * what realized variance (see `volatility`) captures. Realized skewness in
+ * particular has been shown to predict the cross-section of subsequent returns.
+ *
+ * With N returns r and realized variance RV = Σ r²:
+ *   realized skewness = √N · Σ r³ / RV^(3/2)
+ *   realized kurtosis = N · Σ r⁴ / RV²
+ * The √N and N scalings make the estimates comparable across sampling
+ * frequencies. Both return 0 for an empty series or one with no variation.
+ */
+
+/** Realized skewness: √N · Σ r³ / (Σ r²)^(3/2). */
+export function realizedSkewness(returns: readonly number[]): number {
+  const n = returns.length;
+  if (n === 0) return 0;
+  let s2 = 0;
+  let s3 = 0;
+  for (const r of returns) {
+    const r2 = r * r;
+    s2 += r2;
+    s3 += r2 * r;
+  }
+  if (s2 === 0) return 0;
+  return (Math.sqrt(n) * s3) / Math.pow(s2, 1.5);
+}
+
+/** Realized kurtosis: N · Σ r⁴ / (Σ r²)². */
+export function realizedKurtosis(returns: readonly number[]): number {
+  const n = returns.length;
+  if (n === 0) return 0;
+  let s2 = 0;
+  let s4 = 0;
+  for (const r of returns) {
+    const r2 = r * r;
+    s2 += r2;
+    s4 += r2 * r2;
+  }
+  if (s2 === 0) return 0;
+  return (n * s4) / (s2 * s2);
+}

package/src/ofi.ts

@@ -0,0 +1,46 @@
+/**
+ * Order Flow Imbalance (OFI).
+ *
+ * Implements the level-1 OFI of Cont, Kukanov & Stoikov (2014), "The price
+ * impact of order book events". For consecutive best-quote observations
+ * (n-1, n) the event contribution is:
+ *
+ *   e_n =  q^b_n · 1{P^b_n ≥ P^b_{n-1}}  −  q^b_{n-1} · 1{P^b_n ≤ P^b_{n-1}}
+ *        − q^a_n · 1{P^a_n ≤ P^a_{n-1}}  +  q^a_{n-1} · 1{P^a_n ≥ P^a_{n-1}}
+ *
+ * OFI over a window is the sum of e_n. Positive OFI means net buy-side
+ * pressure at the top of book; it is a strong linear predictor of short-term
+ * price moves.
+ */
+import type { L1Quote } from "./types.ts";
+
+/** OFI contribution of a single best-quote transition (prev → curr). */
+export function ofiContribution(prev: L1Quote, curr: L1Quote): number {
+  const bidTerm =
+    (curr.bidPrice >= prev.bidPrice ? curr.bidSize : 0) -
+    (curr.bidPrice <= prev.bidPrice ? prev.bidSize : 0);
+
+  const askTerm =
+    (curr.askPrice >= prev.askPrice ? prev.askSize : 0) -
+    (curr.askPrice <= prev.askPrice ? curr.askSize : 0);
+
+  return bidTerm + askTerm;
+}
+
+/** Per-step OFI contributions for a sequence of quotes (length n-1). */
+export function ofiSeries(quotes: L1Quote[]): number[] {
+  const out: number[] = [];
+  for (let i = 1; i < quotes.length; i++) {
+    out.push(ofiContribution(quotes[i - 1], quotes[i]));
+  }
+  return out;
+}
+
+/** Cumulative OFI over the whole sequence of quotes. */
+export function ofi(quotes: L1Quote[]): number {
+  let total = 0;
+  for (let i = 1; i < quotes.length; i++) {
+    total += ofiContribution(quotes[i - 1], quotes[i]);
+  }
+  return total;
+}