orderflow-metrics 0.24.0

package/src/spreadest.ts

@@ -0,0 +1,75 @@
+/**
+ * Bid-ask spread estimators from daily OHLC data.
+ *
+ * When all you have is low-frequency bars — daily high, low, and close — you can
+ * still back out an estimate of the effective bid-ask spread. Two well-known,
+ * dependency-free estimators:
+ *
+ *  - Corwin & Schultz (2012): the high-low range over two consecutive periods
+ *    reflects both fundamental volatility and the bid-ask bounce. The bounce can
+ *    be isolated because volatility scales with the time interval while the
+ *    spread does not.
+ *  - Abdi & Ranaldo (2017): compares each close to the mid-point of the current
+ *    and the next period's high-low range; their covariance recovers the spread.
+ *
+ * Both return a *proportional* spread (a fraction of price, e.g. 0.01 = 100 bps).
+ * Negative estimates — noise when the true spread is close to zero — are floored
+ * at 0. Prices must be strictly positive.
+ */
+
+export interface Ohlc {
+  high: number;
+  low: number;
+  close: number;
+}
+
+/** 3 - 2√2 ≈ 0.1716, the Corwin-Schultz normalizing constant. */
+const K = 3 - 2 * Math.SQRT2;
+
+/**
+ * Corwin-Schultz (2012) high-low proportional spread estimate, averaged over all
+ * consecutive bar pairs. Per-pair negative estimates are set to 0 before
+ * averaging (as recommended in the paper). Returns 0 for fewer than two bars.
+ */
+export function corwinSchultz(bars: Ohlc[]): number {
+  if (bars.length < 2) return 0;
+  let sum = 0;
+  let n = 0;
+  for (let i = 0; i + 1 < bars.length; i++) {
+    const a = bars[i];
+    const b = bars[i + 1];
+    const hlA = Math.log(a.high / a.low);
+    const hlB = Math.log(b.high / b.low);
+    const beta = hlA * hlA + hlB * hlB;
+    const g = Math.log(Math.max(a.high, b.high) / Math.min(a.low, b.low));
+    const gamma = g * g;
+    const alpha =
+      (Math.sqrt(2 * beta) - Math.sqrt(beta)) / K - Math.sqrt(gamma / K);
+    const s = (2 * (Math.exp(alpha) - 1)) / (1 + Math.exp(alpha));
+    sum += s > 0 ? s : 0;
+    n++;
+  }
+  return n === 0 ? 0 : sum / n;
+}
+
+/**
+ * Abdi-Ranaldo (2017) proportional spread estimate from close, high, and low.
+ * Uses the covariance of each log-close with the mid-range of the current and
+ * next bar: S = sqrt(max(4 · E[(c_t − η_t)(c_t − η_{t+1})], 0)), where
+ * η = (log high + log low) / 2. Returns 0 for fewer than two bars or when the
+ * estimate is negative.
+ */
+export function abdiRanaldo(bars: Ohlc[]): number {
+  if (bars.length < 2) return 0;
+  let sum = 0;
+  let n = 0;
+  for (let t = 0; t + 1 < bars.length; t++) {
+    const c = Math.log(bars[t].close);
+    const etaT = (Math.log(bars[t].high) + Math.log(bars[t].low)) / 2;
+    const etaN = (Math.log(bars[t + 1].high) + Math.log(bars[t + 1].low)) / 2;
+    sum += (c - etaT) * (c - etaN);
+    n++;
+  }
+  const s2 = 4 * (n === 0 ? 0 : sum / n);
+  return s2 > 0 ? Math.sqrt(s2) : 0;
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Core input types for order-flow metrics.
+ *
+ * Prices and sizes are plain numbers; timestamps (if provided) are opaque to
+ * this library — pass whatever epoch unit your feed uses, we never compare
+ * across records.
+ */
+
+export type Side = "buy" | "sell";
+
+/** Top-of-book (level-1) snapshot. */
+export interface L1Quote {
+  ts?: number;
+  bidPrice: number;
+  bidSize: number;
+  askPrice: number;
+  askSize: number;
+}
+
+/** A single executed trade. */
+export interface Trade {
+  ts?: number;
+  price: number;
+  size: number;
+  side: Side;
+}

package/src/volatility.ts

@@ -0,0 +1,36 @@
+/**
+ * Realized volatility from a return series.
+ *
+ * Returns are period returns (e.g. log returns between consecutive prints or
+ * bars). Realized variance is the sum of squared returns; realized volatility
+ * is its square root. Annualized volatility scales the per-period variance by
+ * the number of periods in a year (zero-mean convention, standard for
+ * high-frequency returns).
+ */
+
+/** Realized variance: Σ rᵢ². */
+export function realizedVariance(returns: readonly number[]): number {
+  let sum = 0;
+  for (const r of returns) sum += r * r;
+  return sum;
+}
+
+/** Realized volatility over the sample: √(Σ rᵢ²). */
+export function realizedVolatility(returns: readonly number[]): number {
+  return Math.sqrt(realizedVariance(returns));
+}
+
+/**
+ * Annualized volatility: √( mean(rᵢ²) · periodsPerYear ).
+ *
+ * ``periodsPerYear`` is how many return periods make up a year (e.g. 252 for
+ * daily, 252·390 for 1-minute equity bars). Returns 0 for an empty series.
+ */
+export function annualizedVolatility(
+  returns: readonly number[],
+  periodsPerYear: number,
+): number {
+  const n = returns.length;
+  if (n === 0) return 0;
+  return Math.sqrt((realizedVariance(returns) / n) * periodsPerYear);
+}

package/src/vpin.ts

@@ -0,0 +1,98 @@
+/**
+ * VPIN — Volume-Synchronized Probability of Informed Trading.
+ *
+ * Easley, López de Prado & O'Hara (2012), "Flow Toxicity and Liquidity in a
+ * High-Frequency World". Trades are grouped into equal-volume buckets; each
+ * bucket is split into buy/sell volume by Bulk Volume Classification (BVC)
+ * using the standardized close-to-close price change; VPIN is the average
+ * absolute order imbalance across a rolling window of buckets.
+ *
+ *   V_buy  = V · Φ(ΔP / σ)
+ *   V_sell = V · (1 − Φ(ΔP / σ))
+ *   VPIN   = Σ |V_buy − V_sell| / Σ V     over the window
+ */
+
+export interface VolumeBucket {
+  /** close-to-close price change over the bucket */
+  priceChange: number;
+  /** total traded volume in the bucket */
+  volume: number;
+}
+
+// Abramowitz & Stegun 7.1.26 — max error ≈ 1.5e-7.
+function erf(x: number): number {
+  const t = 1 / (1 + 0.3275911 * Math.abs(x));
+  const y =
+    1 -
+    ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) *
+      t +
+      0.254829592) *
+      t *
+      Math.exp(-x * x);
+  return x >= 0 ? y : -y;
+}
+
+/** Standard normal CDF Φ(x). */
+export function standardNormalCdf(x: number): number {
+  return 0.5 * (1 + erf(x / Math.SQRT2));
+}
+
+/** BVC buy-volume fraction for a bucket, given its price change and σ. */
+export function bvcBuyFraction(priceChange: number, sigma: number): number {
+  if (!(sigma > 0)) return 0.5;
+  return standardNormalCdf(priceChange / sigma);
+}
+
+/** Aggregate a trade stream into equal-volume buckets (splitting trades). */
+export function bucketByVolume(
+  trades: readonly { price: number; size: number }[],
+  bucketSize: number,
+): VolumeBucket[] {
+  if (bucketSize <= 0) throw new Error("bucketSize must be positive");
+  const buckets: VolumeBucket[] = [];
+  let filled = 0;
+  let prevClose = trades.length ? trades[0].price : 0;
+
+  for (const t of trades) {
+    let remaining = t.size;
+    while (filled + remaining >= bucketSize) {
+      remaining -= bucketSize - filled;
+      buckets.push({ priceChange: t.price - prevClose, volume: bucketSize });
+      prevClose = t.price;
+      filled = 0;
+    }
+    filled += remaining;
+  }
+  return buckets;
+}
+
+function populationStd(xs: number[]): number {
+  if (xs.length === 0) return 0;
+  const mean = xs.reduce((a, b) => a + b, 0) / xs.length;
+  const v = xs.reduce((a, b) => a + (b - mean) ** 2, 0) / xs.length;
+  return Math.sqrt(v);
+}
+
+/**
+ * VPIN over the last `window` buckets (default: all of them).
+ * σ for BVC defaults to the std dev of the window's price changes.
+ * Returns a value in [0, 1].
+ */
+export function vpin(
+  buckets: VolumeBucket[],
+  opts: { window?: number; sigma?: number } = {},
+): number {
+  if (buckets.length === 0) return 0;
+  const window = opts.window ?? buckets.length;
+  const slice = buckets.slice(-window);
+  const sigma = opts.sigma ?? populationStd(slice.map((b) => b.priceChange));
+
+  let imbalance = 0;
+  let volume = 0;
+  for (const b of slice) {
+    const buyFrac = bvcBuyFraction(b.priceChange, sigma);
+    imbalance += b.volume * Math.abs(2 * buyFrac - 1);
+    volume += b.volume;
+  }
+  return volume === 0 ? 0 : imbalance / volume;
+}