orderflow-metrics 0.24.0

package/dist/volatility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volatility.d.ts","sourceRoot":"","sources":["../src/volatility.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gCAAgC;AAChC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAInE;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,cAAc,EAAE,MAAM,GACrB,MAAM,CAIR"}

package/dist/volatility.js

@@ -0,0 +1,33 @@
+/**
+ * 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) {
+    let sum = 0;
+    for (const r of returns)
+        sum += r * r;
+    return sum;
+}
+/** Realized volatility over the sample: √(Σ rᵢ²). */
+export function realizedVolatility(returns) {
+    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, periodsPerYear) {
+    const n = returns.length;
+    if (n === 0)
+        return 0;
+    return Math.sqrt((realizedVariance(returns) / n) * periodsPerYear);
+}
+//# sourceMappingURL=volatility.js.map

package/dist/volatility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"volatility.js","sourceRoot":"","sources":["../src/volatility.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gCAAgC;AAChC,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,kBAAkB,CAAC,OAA0B;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA0B,EAC1B,cAAsB;IAEtB,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACzB,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC;AACrE,CAAC"}

package/dist/vpin.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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;
+}
+/** Standard normal CDF Φ(x). */
+export declare function standardNormalCdf(x: number): number;
+/** BVC buy-volume fraction for a bucket, given its price change and σ. */
+export declare function bvcBuyFraction(priceChange: number, sigma: number): number;
+/** Aggregate a trade stream into equal-volume buckets (splitting trades). */
+export declare function bucketByVolume(trades: readonly {
+    price: number;
+    size: number;
+}[], bucketSize: number): VolumeBucket[];
+/**
+ * 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 declare function vpin(buckets: VolumeBucket[], opts?: {
+    window?: number;
+    sigma?: number;
+}): number;
+//# sourceMappingURL=vpin.d.ts.map

package/dist/vpin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpin.d.ts","sourceRoot":"","sources":["../src/vpin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAeD,gCAAgC;AAChC,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,EAClD,UAAU,EAAE,MAAM,GACjB,YAAY,EAAE,CAiBhB;AASD;;;;GAIG;AACH,wBAAgB,IAAI,CAClB,OAAO,EAAE,YAAY,EAAE,EACvB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,MAAM,CAcR"}

package/dist/vpin.js

@@ -0,0 +1,81 @@
+/**
+ * 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
+ */
+// Abramowitz & Stegun 7.1.26 — max error ≈ 1.5e-7.
+function erf(x) {
+    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) {
+    return 0.5 * (1 + erf(x / Math.SQRT2));
+}
+/** BVC buy-volume fraction for a bucket, given its price change and σ. */
+export function bvcBuyFraction(priceChange, sigma) {
+    if (!(sigma > 0))
+        return 0.5;
+    return standardNormalCdf(priceChange / sigma);
+}
+/** Aggregate a trade stream into equal-volume buckets (splitting trades). */
+export function bucketByVolume(trades, bucketSize) {
+    if (bucketSize <= 0)
+        throw new Error("bucketSize must be positive");
+    const buckets = [];
+    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) {
+    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, opts = {}) {
+    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;
+}
+//# sourceMappingURL=vpin.js.map

package/dist/vpin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpin.js","sourceRoot":"","sources":["../src/vpin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "orderflow-metrics",
+  "version": "0.24.0",
+  "description": "Microstructure metrics in dependency-free TypeScript — OFI, VPIN, information-driven bars, market impact (square-root & Almgren-Chriss), markouts, implementation shortfall, high-low spread estimators (Corwin-Schultz, Abdi-Ranaldo), range-based volatility (Parkinson, Garman-Klass, Rogers-Satchell, Yang-Zhang), Hurst exponent, realized skewness & kurtosis, bipower variation & jump detection, realized semivariance & signed jump variation, order-flow entropy, online/streaming estimators (Welford, EWMA, rolling window), realized covariance/correlation/beta, Kyle's lambda, trade-sign classification, Amihud illiquidity.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --experimental-strip-types --test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "market-microstructure",
+    "order-flow-imbalance",
+    "ofi",
+    "vpin",
+    "order-book",
+    "information-driven-bars",
+    "dollar-bars",
+    "realized-volatility",
+    "realized-covariance",
+    "market-impact",
+    "kyle-lambda",
+    "market-data",
+    "hft",
+    "algorithmic-trading",
+    "trading",
+    "quantitative-finance",
+    "typescript"
+  ],
+  "author": "TwoWayMind (RATE LTD)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/twowaymind/orderflow-metrics.git"
+  },
+  "bugs": {
+    "url": "https://github.com/twowaymind/orderflow-metrics/issues"
+  },
+  "homepage": "https://twowaymind.com",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/bars.ts

@@ -0,0 +1,141 @@
+/**
+ * Information-driven bars.
+ *
+ * Sampling a raw trade stream on a fixed *time* grid (1m, 5m, …) oversamples
+ * quiet periods and undersamples busy ones, and produces returns that are far
+ * from IID. Sampling on *activity* instead — a bar every N ticks, every N
+ * units of volume, or every N units of traded value — yields bars with much
+ * better statistical properties (López de Prado, *Advances in Financial
+ * Machine Learning*, ch. 2). These bars are the natural upstream sampling
+ * layer for the rest of this library: build them first, then compute OFI,
+ * imbalance, volatility, VPIN, … on the resulting series.
+ *
+ * Trades are never split across bars: the trade that crosses the threshold is
+ * included whole and closes the bar, so `volume`/`dollar` may slightly exceed
+ * the threshold. A trailing partial bar (below threshold at end of stream) is
+ * dropped, matching `bucketByVolume` in the VPIN module.
+ */
+import type { Trade } from "./types.ts";
+
+/** One OHLCV bar aggregated from a slice of trades. */
+export interface Bar {
+  /** Price of the first trade in the bar. */
+  open: number;
+  /** Highest trade price in the bar. */
+  high: number;
+  /** Lowest trade price in the bar. */
+  low: number;
+  /** Price of the last trade in the bar. */
+  close: number;
+  /** Total traded size. */
+  volume: number;
+  /** Total traded value, Σ price·size. */
+  dollar: number;
+  /** Volume-weighted average price, `dollar / volume`. */
+  vwap: number;
+  /** Number of trades aggregated into the bar. */
+  ticks: number;
+  /** Size of buyer-initiated trades. */
+  buyVolume: number;
+  /** Size of seller-initiated trades. */
+  sellVolume: number;
+  /** Timestamp of the first trade, if the feed provided one. */
+  start?: number;
+  /** Timestamp of the last trade, if the feed provided one. */
+  end?: number;
+}
+
+/** Aggregate a non-empty slice of trades into a single bar. */
+function buildBar(trades: readonly Trade[]): Bar {
+  const first = trades[0];
+  const last = trades[trades.length - 1];
+
+  let high = first.price;
+  let low = first.price;
+  let volume = 0;
+  let dollar = 0;
+  let buyVolume = 0;
+  let sellVolume = 0;
+
+  for (const t of trades) {
+    if (t.price > high) high = t.price;
+    if (t.price < low) low = t.price;
+    volume += t.size;
+    dollar += t.price * t.size;
+    if (t.side === "buy") buyVolume += t.size;
+    else sellVolume += t.size;
+  }
+
+  const bar: Bar = {
+    open: first.price,
+    high,
+    low,
+    close: last.price,
+    volume,
+    dollar,
+    vwap: volume > 0 ? dollar / volume : first.price,
+    ticks: trades.length,
+    buyVolume,
+    sellVolume,
+  };
+  if (first.ts !== undefined) bar.start = first.ts;
+  if (last.ts !== undefined) bar.end = last.ts;
+  return bar;
+}
+
+/**
+ * Emit a bar every `threshold` trades (tick bars).
+ *
+ * @param threshold number of trades per bar (integer ≥ 1)
+ */
+export function tickBars(trades: readonly Trade[], threshold: number): Bar[] {
+  const step = Math.floor(threshold);
+  if (step < 1) return [];
+  const bars: Bar[] = [];
+  for (let i = 0; i + step <= trades.length; i += step) {
+    bars.push(buildBar(trades.slice(i, i + step)));
+  }
+  return bars;
+}
+
+/**
+ * Emit a bar each time cumulative size reaches `threshold` (volume bars).
+ * The trade that crosses the threshold closes the bar and is included whole.
+ *
+ * @param threshold volume per bar (> 0)
+ */
+export function volumeBars(trades: readonly Trade[], threshold: number): Bar[] {
+  return accumulate(trades, threshold, (t) => t.size);
+}
+
+/**
+ * Emit a bar each time cumulative traded value (Σ price·size) reaches
+ * `threshold` (dollar bars). Dollar bars are the most robust of the three to
+ * changes in price level and are usually preferred (López de Prado, 2018).
+ *
+ * @param threshold traded value per bar (> 0)
+ */
+export function dollarBars(trades: readonly Trade[], threshold: number): Bar[] {
+  return accumulate(trades, threshold, (t) => t.price * t.size);
+}
+
+/** Shared accumulator for volume / dollar bars. */
+function accumulate(
+  trades: readonly Trade[],
+  threshold: number,
+  weight: (t: Trade) => number,
+): Bar[] {
+  if (!(threshold > 0)) return [];
+  const bars: Bar[] = [];
+  let start = 0;
+  let acc = 0;
+  for (let i = 0; i < trades.length; i++) {
+    acc += weight(trades[i]);
+    if (acc >= threshold) {
+      bars.push(buildBar(trades.slice(start, i + 1)));
+      start = i + 1;
+      acc = 0;
+    }
+  }
+  return bars;
+}

package/src/classify.ts

@@ -0,0 +1,59 @@
+/**
+ * Trade-sign classification.
+ *
+ * Public trade prints usually don't tell you which side was the aggressor.
+ * These rules infer it, so downstream OFI / imbalance / VPIN inputs can be
+ * signed. Output is +1 (buyer-initiated), −1 (seller-initiated), 0 (unknown).
+ */
+
+export type Sign = 1 | -1 | 0;
+
+/**
+ * Tick rule: classify by the change vs the previous trade price.
+ * An unchanged ("zero tick") price carries the last non-zero sign; the first
+ * trade is unclassifiable (0).
+ */
+export function tickRule(prices: readonly number[]): Sign[] {
+  const out: Sign[] = [];
+  let last: Sign = 0;
+  for (let i = 0; i < prices.length; i++) {
+    if (i > 0) {
+      const d = prices[i] - prices[i - 1];
+      if (d > 0) last = 1;
+      else if (d < 0) last = -1;
+      // d === 0 -> keep last (zero-tick)
+    }
+    out.push(last);
+  }
+  return out;
+}
+
+export interface PriceVsMid {
+  price: number;
+  mid: number;
+}
+
+/**
+ * Lee-Ready (1991): quote rule first — a print above the prevailing mid is
+ * buyer-initiated, below is seller-initiated — with the tick rule breaking
+ * at-the-mid ties.
+ */
+export function leeReady(obs: readonly PriceVsMid[]): Sign[] {
+  const out: Sign[] = [];
+  let last: Sign = 0;
+  for (let i = 0; i < obs.length; i++) {
+    const { price, mid } = obs[i];
+    let sign: Sign;
+    if (price > mid) sign = 1;
+    else if (price < mid) sign = -1;
+    else if (i > 0) {
+      const d = price - obs[i - 1].price;
+      sign = d > 0 ? 1 : d < 0 ? -1 : last;
+    } else {
+      sign = 0;
+    }
+    if (sign !== 0) last = sign;
+    out.push(sign);
+  }
+  return out;
+}

package/src/covariance.ts

@@ -0,0 +1,72 @@
+/**
+ * Realized covariance, correlation, and beta between two return series.
+ *
+ * Single-asset volatility says how much one instrument moved; trading and risk
+ * live in how instruments move *together*. Summing the products of contemporaneous
+ * returns gives the realized (co)variance — the model-free, high-frequency analogue
+ * of covariance:
+ *
+ *   realized covariance   = Σ xᵢ · yᵢ
+ *   realized correlation  = Σ xᵢyᵢ / ( √Σxᵢ² · √Σyᵢ² )   (in [−1, 1])
+ *   realized beta         = Σ aᵢ·mᵢ / Σ mᵢ²              (asset a vs market m)
+ *
+ * The two series are paired element-wise over their common length, so they must
+ * be aligned to the same sampling grid (equal length, matching timestamps).
+ * Correlation is scale-free; beta is the covariance of an asset with a market,
+ * normalized by the market's variance — the sensitivity of the asset to it.
+ */
+
+/** Σ xᵢyᵢ over the two series' common length. Both empty → 0. */
+function sumProduct(x: readonly number[], y: readonly number[]): number {
+  const n = Math.min(x.length, y.length);
+  let s = 0;
+  for (let i = 0; i < n; i++) s += x[i] * y[i];
+  return s;
+}
+
+/**
+ * Realized covariance: Σ xᵢyᵢ over contemporaneous returns. Symmetric in its
+ * arguments; returns 0 for empty input. Series are paired over their common
+ * length, so align them to the same sampling grid first.
+ */
+export function realizedCovariance(x: readonly number[], y: readonly number[]): number {
+  return sumProduct(x, y);
+}
+
+/**
+ * Realized correlation: Σ xᵢyᵢ / (√Σxᵢ² · √Σyᵢ²), in [−1, 1]. Scale-free measure
+ * of co-movement. Returns 0 when either series has zero realized variance (or is
+ * empty).
+ */
+export function realizedCorrelation(x: readonly number[], y: readonly number[]): number {
+  const n = Math.min(x.length, y.length);
+  if (n === 0) return 0;
+  let sxy = 0;
+  let sxx = 0;
+  let syy = 0;
+  for (let i = 0; i < n; i++) {
+    sxy += x[i] * y[i];
+    sxx += x[i] * x[i];
+    syy += y[i] * y[i];
+  }
+  const denom = Math.sqrt(sxx) * Math.sqrt(syy);
+  return denom > 0 ? sxy / denom : 0;
+}
+
+/**
+ * Realized beta of an asset against a market/benchmark: Σ aᵢmᵢ / Σ mᵢ², i.e. the
+ * realized covariance of the two divided by the market's realized variance — the
+ * asset's sensitivity to the market. Returns 0 when the market has zero realized
+ * variance (or the input is empty).
+ */
+export function realizedBeta(asset: readonly number[], market: readonly number[]): number {
+  const n = Math.min(asset.length, market.length);
+  if (n === 0) return 0;
+  let cov = 0;
+  let varM = 0;
+  for (let i = 0; i < n; i++) {
+    cov += asset[i] * market[i];
+    varM += market[i] * market[i];
+  }
+  return varM > 0 ? cov / varM : 0;
+}

package/src/efficiency.ts

@@ -0,0 +1,64 @@
+/**
+ * Market-efficiency diagnostics on a return series.
+ *
+ * Autocorrelation and the Lo-MacKinlay variance ratio tell you whether a
+ * series behaves like a random walk, mean-reverts, or trends — the kind of
+ * structure execution and market-making models care about.
+ */
+
+/**
+ * Lag-`lag` autocorrelation of a return series (biased estimator, denominator
+ * is the full-sample variance). Range roughly [-1, 1]. 0 for degenerate input.
+ */
+export function autocorrelation(returns: readonly number[], lag: number): number {
+  const n = returns.length;
+  if (lag < 1 || n <= lag) return 0;
+
+  const mean = returns.reduce((a, b) => a + b, 0) / n;
+  let den = 0;
+  for (const r of returns) den += (r - mean) * (r - mean);
+  if (den === 0) return 0;
+
+  let num = 0;
+  for (let t = lag; t < n; t++) {
+    num += (returns[t] - mean) * (returns[t - lag] - mean);
+  }
+  return num / den;
+}
+
+/**
+ * Variance ratio VR(q) = Var(q-period return) / (q · Var(1-period return))
+ * over overlapping q-period returns (Lo & MacKinlay, 1988).
+ *
+ *   VR ≈ 1  random walk
+ *   VR < 1  mean-reverting
+ *   VR > 1  trending / positively autocorrelated
+ *
+ * Returns 1 for degenerate input (q ≥ length, or zero one-period variance).
+ */
+export function varianceRatio(returns: readonly number[], q: number): number {
+  const n = returns.length;
+  // Need at least two overlapping q-period returns for a meaningful variance,
+  // i.e. n > q. At n <= q the estimate is degenerate — return 1 (random walk).
+  if (q < 1 || n <= q) return 1;
+
+  const mean = returns.reduce((a, b) => a + b, 0) / n;
+  let var1 = 0;
+  for (const r of returns) var1 += (r - mean) * (r - mean);
+  var1 /= n;
+  if (var1 === 0) return 1;
+
+  const qSums: number[] = [];
+  for (let j = 0; j + q <= n; j++) {
+    let s = 0;
+    for (let i = j; i < j + q; i++) s += returns[i];
+    qSums.push(s);
+  }
+
+  const meanQ = qSums.reduce((a, b) => a + b, 0) / qSums.length;
+  let varQ = 0;
+  for (const s of qSums) varQ += (s - meanQ) * (s - meanQ);
+  varQ /= qSums.length;
+
+  return varQ / (q * var1);
+}

package/src/entropy.ts

@@ -0,0 +1,67 @@
+/**
+ * Order-flow entropy: how predictable is a stream of trades or returns?
+ *
+ * Shannon entropy measures the average surprise in a discrete distribution.
+ * Applied to microstructure, it quantifies the *balance* and *predictability*
+ * of order flow: a stream that is almost all buys (or a return series that only
+ * ticks one way) carries little surprise — low entropy — and is easier to
+ * anticipate, while a perfectly balanced, unpredictable stream is at maximum
+ * entropy. Persistently low flow entropy is a hallmark of directional,
+ * potentially informed activity.
+ *
+ *   H = − Σᵢ pᵢ · log₂ pᵢ        (in bits; pᵢ = countᵢ / Σ counts)
+ *
+ * Entropy is reported in bits (base-2), so two equally likely outcomes give
+ * exactly 1 bit and k equally likely outcomes give log₂ k bits.
+ */
+
+/**
+ * Shannon entropy (in bits) of a discrete distribution given category counts
+ * (or probabilities — any non-negative weights). Zero and negative entries are
+ * ignored; the remaining weights are normalized to sum to 1. Returns 0 when
+ * fewer than two categories carry positive weight.
+ */
+export function shannonEntropy(counts: readonly number[]): number {
+  let total = 0;
+  for (const c of counts) if (c > 0) total += c;
+  if (total <= 0) return 0;
+  let h = 0;
+  for (const c of counts) {
+    if (c > 0) {
+      const p = c / total;
+      h -= p * Math.log2(p);
+    }
+  }
+  return h;
+}
+
+/**
+ * Normalized entropy: Shannon entropy divided by log₂(k), where k is the number
+ * of categories carrying positive weight. Maps entropy onto [0, 1] — 0 is fully
+ * concentrated (one-sided), 1 is perfectly uniform — so distributions with
+ * different numbers of categories are comparable. Returns 0 when fewer than two
+ * categories carry positive weight.
+ */
+export function normalizedEntropy(counts: readonly number[]): number {
+  let k = 0;
+  for (const c of counts) if (c > 0) k++;
+  if (k < 2) return 0;
+  return shannonEntropy(counts) / Math.log2(k);
+}
+
+/**
+ * Sign entropy: the Shannon entropy (in bits, in [0, 1]) of the up/down split
+ * of a return or signed-flow series. Zero entries are ignored. 1 bit means
+ * perfectly balanced two-sided flow; values near 0 mean the flow is heavily
+ * one-sided (and thus more predictable). Returns 0 for an empty or single-sided
+ * series.
+ */
+export function signEntropy(values: readonly number[]): number {
+  let up = 0;
+  let down = 0;
+  for (const v of values) {
+    if (v > 0) up++;
+    else if (v < 0) down++;
+  }
+  return shannonEntropy([up, down]);
+}