orderflow-metrics 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 This project follows [Semantic Versioning](https://semver.org/); pre-1.0 the
 public API may still change between minor versions.
 
+## [0.27.0] - 2026-08-28
+
+### Added
+- Two-Scale Realized Variance (`tsrv`) — `twoScaleRealizedVariance` and
+  `twoScaleRealizedVolatility`, a *consistent*, microstructure-noise-corrected
+  estimator of integrated variance (Zhang, Mykland & Aït-Sahalia 2005). It
+  combines a slow subsampled RV with the fast all-ticks RV and subtracts the
+  noise bias — the estimator-grade sequel to the diagnostics in the `noise`
+  module. Test suite included. (Python: 0.15.0.)
+
+## [0.26.0] - 2026-08-27
+
+### Added
+- Microstructure-noise-aware realized variance (`noise`) — `noiseVariance`
+  (variance of the microstructure noise, ≈ RV_finest / 2n; Zhang, Mykland &
+  Aït-Sahalia 2005), `sparseRealizedVariance` (RV on a coarser grid, averaged
+  over every offset by subsampling so no data is wasted — `step = 1` reproduces
+  plain RV, larger steps suppress noise bias) and `volatilitySignature` (RV as a
+  function of sampling step: the classic signature plot whose blow-up at fine
+  steps is the fingerprint of microstructure noise). Test suite included.
+  (Python: 0.14.0.)
+
 ## [0.25.0] - 2026-08-26
 
 ### Added

package/dist/index.d.ts

@@ -32,6 +32,9 @@ export { hurstExponent } from "./hurst.ts";
 export { realizedSkewness, realizedKurtosis } from "./moments.ts";
 export { bipowerVariation, jumpVariation, relativeJumpVariation, } from "./jumps.ts";
 export { minRV, medRV, realizedQuarticity } from "./robustvol.ts";
+export type { SignaturePoint } from "./noise.ts";
+export { noiseVariance, sparseRealizedVariance, volatilitySignature, } from "./noise.ts";
+export { twoScaleRealizedVariance, twoScaleRealizedVolatility, } from "./tsrv.ts";
 export type { Semivariance } from "./semivar.ts";
 export { realizedSemivariance, downsideVarianceRatio, signedJumpVariation, } from "./semivar.ts";
 export { shannonEntropy, normalizedEntropy, signEntropy, } from "./entropy.ts";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -19,6 +19,8 @@ export { hurstExponent } from "./hurst.js";
 export { realizedSkewness, realizedKurtosis } from "./moments.js";
 export { bipowerVariation, jumpVariation, relativeJumpVariation, } from "./jumps.js";
 export { minRV, medRV, realizedQuarticity } from "./robustvol.js";
+export { noiseVariance, sparseRealizedVariance, volatilitySignature, } from "./noise.js";
+export { twoScaleRealizedVariance, twoScaleRealizedVolatility, } from "./tsrv.js";
 export { realizedSemivariance, downsideVarianceRatio, signedJumpVariation, } from "./semivar.js";
 export { shannonEntropy, normalizedEntropy, signEntropy, } from "./entropy.js";
 export { Welford, Ewma, EwmaVariance, RollingWindow, } from "./online.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EACL,IAAI,EACJ,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,OAAO,EACP,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EACL,IAAI,EACJ,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,OAAO,EACP,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC"}

package/dist/noise.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Microstructure-noise-aware realized variance.
+ *
+ * At the finest sampling frequency, realized variance is badly biased upward:
+ * observed prices are the "true" price plus microstructure noise (bid-ask
+ * bounce, discreteness, latency), and squaring tiny bounce returns pumps up the
+ * sum. Sample more coarsely and the noise averages out — but you throw away
+ * data. These tools let you see, quantify, and reduce that bias.
+ *
+ *   noiseVariance          — the variance of the noise itself, ≈ RV_finest / 2n
+ *                            (Zhang, Mykland & Aït-Sahalia, 2005)
+ *   sparseRealizedVariance — RV on a coarser grid, averaged over every offset
+ *                            (subsampling), so no data is wasted
+ *   volatilitySignature    — RV as a function of sampling step: the classic
+ *                            "signature plot" whose blow-up at fine steps is the
+ *                            visual fingerprint of microstructure noise
+ *
+ * Every function takes a series of (fine-grid) returns.
+ */
+/**
+ * Estimate the variance of the microstructure noise. Under the additive-noise
+ * model the finest-grid realized variance is dominated by noise and converges
+ * to 2n·(noise variance), so the noise variance is estimated as RV / (2n).
+ * Returns 0 for an empty series.
+ */
+export declare function noiseVariance(returns: readonly number[]): number;
+/**
+ * Realized variance on a grid `step` times coarser than the raw returns,
+ * averaged over all `step` possible starting offsets (subsampling) so every
+ * observation is used. `step = 1` reproduces plain realized variance; larger
+ * steps suppress microstructure-noise bias at the cost of resolution. Returns 0
+ * for `step < 1`, an empty series, or a step too large to form any block.
+ */
+export declare function sparseRealizedVariance(returns: readonly number[], step: number): number;
+/** One point of a volatility-signature curve. */
+export interface SignaturePoint {
+    /** Sampling step (in raw-return units). */
+    step: number;
+    /** Subsampled realized variance at that step. */
+    realizedVariance: number;
+}
+/**
+ * The volatility signature: subsampled realized variance at each sampling step
+ * in `steps`. Plotted against the step, the curve typically starts high (noise
+ * inflated) at step 1 and settles toward the true integrated variance as the
+ * step grows — the shape that diagnoses how much microstructure noise a series
+ * carries. Steps are used as given (deduplication and ordering are the caller's
+ * choice).
+ */
+export declare function volatilitySignature(returns: readonly number[], steps: readonly number[]): SignaturePoint[];
+//# sourceMappingURL=noise.d.ts.map

package/dist/noise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noise.d.ts","sourceRoot":"","sources":["../src/noise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAIhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,EAAE,MAAM,GACX,MAAM,CA2BR;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,cAAc,EAAE,CAKlB"}

package/dist/noise.js

@@ -0,0 +1,89 @@
+/**
+ * Microstructure-noise-aware realized variance.
+ *
+ * At the finest sampling frequency, realized variance is badly biased upward:
+ * observed prices are the "true" price plus microstructure noise (bid-ask
+ * bounce, discreteness, latency), and squaring tiny bounce returns pumps up the
+ * sum. Sample more coarsely and the noise averages out — but you throw away
+ * data. These tools let you see, quantify, and reduce that bias.
+ *
+ *   noiseVariance          — the variance of the noise itself, ≈ RV_finest / 2n
+ *                            (Zhang, Mykland & Aït-Sahalia, 2005)
+ *   sparseRealizedVariance — RV on a coarser grid, averaged over every offset
+ *                            (subsampling), so no data is wasted
+ *   volatilitySignature    — RV as a function of sampling step: the classic
+ *                            "signature plot" whose blow-up at fine steps is the
+ *                            visual fingerprint of microstructure noise
+ *
+ * Every function takes a series of (fine-grid) returns.
+ */
+/** Σ rᵢ² over the full, finest grid (local helper). */
+function realizedVarAll(returns) {
+    let s = 0;
+    for (const r of returns)
+        s += r * r;
+    return s;
+}
+/**
+ * Estimate the variance of the microstructure noise. Under the additive-noise
+ * model the finest-grid realized variance is dominated by noise and converges
+ * to 2n·(noise variance), so the noise variance is estimated as RV / (2n).
+ * Returns 0 for an empty series.
+ */
+export function noiseVariance(returns) {
+    const n = returns.length;
+    if (n < 1)
+        return 0;
+    return realizedVarAll(returns) / (2 * n);
+}
+/**
+ * Realized variance on a grid `step` times coarser than the raw returns,
+ * averaged over all `step` possible starting offsets (subsampling) so every
+ * observation is used. `step = 1` reproduces plain realized variance; larger
+ * steps suppress microstructure-noise bias at the cost of resolution. Returns 0
+ * for `step < 1`, an empty series, or a step too large to form any block.
+ */
+export function sparseRealizedVariance(returns, step) {
+    const n = returns.length;
+    const k = Math.floor(step);
+    if (k < 1 || n < 1)
+        return 0;
+    if (k === 1)
+        return realizedVarAll(returns);
+    // cumulative log-prices P[0..n], P[i] = Σ returns[0..i-1]
+    const P = new Array(n + 1);
+    P[0] = 0;
+    for (let i = 0; i < n; i++)
+        P[i + 1] = P[i] + returns[i];
+    let total = 0;
+    let grids = 0;
+    for (let g = 0; g < k; g++) {
+        let s = 0;
+        let blocks = 0;
+        for (let idx = g; idx + k <= n; idx += k) {
+            const d = P[idx + k] - P[idx];
+            s += d * d;
+            blocks++;
+        }
+        if (blocks > 0) {
+            total += s;
+            grids++;
+        }
+    }
+    return grids > 0 ? total / grids : 0;
+}
+/**
+ * The volatility signature: subsampled realized variance at each sampling step
+ * in `steps`. Plotted against the step, the curve typically starts high (noise
+ * inflated) at step 1 and settles toward the true integrated variance as the
+ * step grows — the shape that diagnoses how much microstructure noise a series
+ * carries. Steps are used as given (deduplication and ordering are the caller's
+ * choice).
+ */
+export function volatilitySignature(returns, steps) {
+    return steps.map((step) => ({
+        step,
+        realizedVariance: sparseRealizedVariance(returns, step),
+    }));
+}
+//# sourceMappingURL=noise.js.map

package/dist/noise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noise.js","sourceRoot":"","sources":["../src/noise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uDAAuD;AACvD,SAAS,cAAc,CAAC,OAA0B;IAChD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAA0B;IACtD,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACzB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA0B,EAC1B,IAAY;IAEZ,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACzB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;IAE5C,0DAA0D;IAC1D,MAAM,CAAC,GAAG,IAAI,KAAK,CAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACT,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEzD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACX,MAAM,EAAE,CAAC;QACX,CAAC;QACD,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,KAAK,IAAI,CAAC,CAAC;YACX,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC;AAUD;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA0B,EAC1B,KAAwB;IAExB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI;QACJ,gBAAgB,EAAE,sBAAsB,CAAC,OAAO,EAAE,IAAI,CAAC;KACxD,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/tsrv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Two-Scale Realized Variance (TSRV) — Zhang, Mykland & Aït-Sahalia (2005).
+ *
+ * Plain realized variance is biased upward by microstructure noise, and sparse
+ * (subsampled) realized variance reduces that bias but doesn't remove it. TSRV
+ * removes it: it combines two sampling scales — a slow, subsampled RV and the
+ * fast all-ticks RV (which is essentially a pure measurement of the noise) — and
+ * subtracts a bias correction, yielding a *consistent* estimator of integrated
+ * variance that uses every observation.
+ *
+ *   TSRV = (1 − n̄/n)⁻¹ · ( RV_sparse(K) − (n̄/n) · RV_all )
+ *
+ * where RV_all is the finest-grid Σrᵢ², RV_sparse(K) is realized variance on a
+ * grid K times coarser averaged over all K offsets (subsampling), and
+ * n̄ = (n − K + 1)/K is the average number of returns per slow subgrid. The
+ * leading factor is the small-sample bias adjustment. `K` (the slow scale) is
+ * best read off a volatility signature plot (see the `noise` module).
+ */
+/**
+ * Two-scale realized variance: a microstructure-noise-consistent estimator of
+ * integrated variance. `slowScale` (K ≥ 2) is the coarse sampling factor.
+ * Returns plain realized variance for `slowScale < 2` (no second scale) and 0
+ * for fewer than two returns. In heavy-noise / very-small-sample cases the
+ * estimate can be slightly negative, like any bias-corrected variance
+ * estimator; floor it yourself if you need a non-negative value.
+ */
+export declare function twoScaleRealizedVariance(returns: readonly number[], slowScale: number): number;
+/**
+ * Two-scale realized volatility: the square root of `twoScaleRealizedVariance`,
+ * floored at 0 (a negative small-sample estimate is treated as zero variance).
+ */
+export declare function twoScaleRealizedVolatility(returns: readonly number[], slowScale: number): number;
+//# sourceMappingURL=tsrv.d.ts.map

package/dist/tsrv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsrv.d.ts","sourceRoot":"","sources":["../src/tsrv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,MAAM,GAChB,MAAM,CAYR;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,MAAM,GAChB,MAAM,CAGR"}

package/dist/tsrv.js

@@ -0,0 +1,57 @@
+/**
+ * Two-Scale Realized Variance (TSRV) — Zhang, Mykland & Aït-Sahalia (2005).
+ *
+ * Plain realized variance is biased upward by microstructure noise, and sparse
+ * (subsampled) realized variance reduces that bias but doesn't remove it. TSRV
+ * removes it: it combines two sampling scales — a slow, subsampled RV and the
+ * fast all-ticks RV (which is essentially a pure measurement of the noise) — and
+ * subtracts a bias correction, yielding a *consistent* estimator of integrated
+ * variance that uses every observation.
+ *
+ *   TSRV = (1 − n̄/n)⁻¹ · ( RV_sparse(K) − (n̄/n) · RV_all )
+ *
+ * where RV_all is the finest-grid Σrᵢ², RV_sparse(K) is realized variance on a
+ * grid K times coarser averaged over all K offsets (subsampling), and
+ * n̄ = (n − K + 1)/K is the average number of returns per slow subgrid. The
+ * leading factor is the small-sample bias adjustment. `K` (the slow scale) is
+ * best read off a volatility signature plot (see the `noise` module).
+ */
+import { sparseRealizedVariance } from "./noise.js";
+function realizedVarAll(returns) {
+    let s = 0;
+    for (const r of returns)
+        s += r * r;
+    return s;
+}
+/**
+ * Two-scale realized variance: a microstructure-noise-consistent estimator of
+ * integrated variance. `slowScale` (K ≥ 2) is the coarse sampling factor.
+ * Returns plain realized variance for `slowScale < 2` (no second scale) and 0
+ * for fewer than two returns. In heavy-noise / very-small-sample cases the
+ * estimate can be slightly negative, like any bias-corrected variance
+ * estimator; floor it yourself if you need a non-negative value.
+ */
+export function twoScaleRealizedVariance(returns, slowScale) {
+    const n = returns.length;
+    const k = Math.floor(slowScale);
+    if (n < 2)
+        return 0;
+    if (k < 2)
+        return realizedVarAll(returns);
+    const rvSparse = sparseRealizedVariance(returns, k);
+    const rvAll = realizedVarAll(returns);
+    const nBar = (n - k + 1) / k;
+    const adj = 1 - nBar / n;
+    if (adj <= 0)
+        return rvSparse; // too few observations for the correction
+    return (rvSparse - (nBar / n) * rvAll) / adj;
+}
+/**
+ * Two-scale realized volatility: the square root of `twoScaleRealizedVariance`,
+ * floored at 0 (a negative small-sample estimate is treated as zero variance).
+ */
+export function twoScaleRealizedVolatility(returns, slowScale) {
+    const v = twoScaleRealizedVariance(returns, slowScale);
+    return Math.sqrt(v > 0 ? v : 0);
+}
+//# sourceMappingURL=tsrv.js.map

package/dist/tsrv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsrv.js","sourceRoot":"","sources":["../src/tsrv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,SAAS,cAAc,CAAC,OAA0B;IAChD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA0B,EAC1B,SAAiB;IAEjB,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IACzB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IACzB,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC,CAAC,0CAA0C;IACzE,OAAO,CAAC,QAAQ,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA0B,EAC1B,SAAiB;IAEjB,MAAM,CAAC,GAAG,wBAAwB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orderflow-metrics",
-  "version": "0.25.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, jump-robust variance (MinRV, MedRV) & realized quarticity, 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.",
+  "version": "0.27.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, jump-robust variance (MinRV, MedRV) & realized quarticity, realized semivariance & signed jump variation, order-flow entropy, online/streaming estimators (Welford, EWMA, rolling window), realized covariance/correlation/beta, microstructure-noise-robust variance (subsampling, volatility signature, two-scale realized variance), Kyle's lambda, trade-sign classification, Amihud illiquidity.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/index.ts

@@ -64,6 +64,16 @@ export {
   relativeJumpVariation,
 } from "./jumps.ts";
 export { minRV, medRV, realizedQuarticity } from "./robustvol.ts";
+export type { SignaturePoint } from "./noise.ts";
+export {
+  noiseVariance,
+  sparseRealizedVariance,
+  volatilitySignature,
+} from "./noise.ts";
+export {
+  twoScaleRealizedVariance,
+  twoScaleRealizedVolatility,
+} from "./tsrv.ts";
 export type { Semivariance } from "./semivar.ts";
 export {
   realizedSemivariance,

package/src/noise.ts

@@ -0,0 +1,103 @@
+/**
+ * Microstructure-noise-aware realized variance.
+ *
+ * At the finest sampling frequency, realized variance is badly biased upward:
+ * observed prices are the "true" price plus microstructure noise (bid-ask
+ * bounce, discreteness, latency), and squaring tiny bounce returns pumps up the
+ * sum. Sample more coarsely and the noise averages out — but you throw away
+ * data. These tools let you see, quantify, and reduce that bias.
+ *
+ *   noiseVariance          — the variance of the noise itself, ≈ RV_finest / 2n
+ *                            (Zhang, Mykland & Aït-Sahalia, 2005)
+ *   sparseRealizedVariance — RV on a coarser grid, averaged over every offset
+ *                            (subsampling), so no data is wasted
+ *   volatilitySignature    — RV as a function of sampling step: the classic
+ *                            "signature plot" whose blow-up at fine steps is the
+ *                            visual fingerprint of microstructure noise
+ *
+ * Every function takes a series of (fine-grid) returns.
+ */
+
+/** Σ rᵢ² over the full, finest grid (local helper). */
+function realizedVarAll(returns: readonly number[]): number {
+  let s = 0;
+  for (const r of returns) s += r * r;
+  return s;
+}
+
+/**
+ * Estimate the variance of the microstructure noise. Under the additive-noise
+ * model the finest-grid realized variance is dominated by noise and converges
+ * to 2n·(noise variance), so the noise variance is estimated as RV / (2n).
+ * Returns 0 for an empty series.
+ */
+export function noiseVariance(returns: readonly number[]): number {
+  const n = returns.length;
+  if (n < 1) return 0;
+  return realizedVarAll(returns) / (2 * n);
+}
+
+/**
+ * Realized variance on a grid `step` times coarser than the raw returns,
+ * averaged over all `step` possible starting offsets (subsampling) so every
+ * observation is used. `step = 1` reproduces plain realized variance; larger
+ * steps suppress microstructure-noise bias at the cost of resolution. Returns 0
+ * for `step < 1`, an empty series, or a step too large to form any block.
+ */
+export function sparseRealizedVariance(
+  returns: readonly number[],
+  step: number,
+): number {
+  const n = returns.length;
+  const k = Math.floor(step);
+  if (k < 1 || n < 1) return 0;
+  if (k === 1) return realizedVarAll(returns);
+
+  // cumulative log-prices P[0..n], P[i] = Σ returns[0..i-1]
+  const P = new Array<number>(n + 1);
+  P[0] = 0;
+  for (let i = 0; i < n; i++) P[i + 1] = P[i] + returns[i];
+
+  let total = 0;
+  let grids = 0;
+  for (let g = 0; g < k; g++) {
+    let s = 0;
+    let blocks = 0;
+    for (let idx = g; idx + k <= n; idx += k) {
+      const d = P[idx + k] - P[idx];
+      s += d * d;
+      blocks++;
+    }
+    if (blocks > 0) {
+      total += s;
+      grids++;
+    }
+  }
+  return grids > 0 ? total / grids : 0;
+}
+
+/** One point of a volatility-signature curve. */
+export interface SignaturePoint {
+  /** Sampling step (in raw-return units). */
+  step: number;
+  /** Subsampled realized variance at that step. */
+  realizedVariance: number;
+}
+
+/**
+ * The volatility signature: subsampled realized variance at each sampling step
+ * in `steps`. Plotted against the step, the curve typically starts high (noise
+ * inflated) at step 1 and settles toward the true integrated variance as the
+ * step grows — the shape that diagnoses how much microstructure noise a series
+ * carries. Steps are used as given (deduplication and ordering are the caller's
+ * choice).
+ */
+export function volatilitySignature(
+  returns: readonly number[],
+  steps: readonly number[],
+): SignaturePoint[] {
+  return steps.map((step) => ({
+    step,
+    realizedVariance: sparseRealizedVariance(returns, step),
+  }));
+}

package/src/tsrv.ts

@@ -0,0 +1,63 @@
+/**
+ * Two-Scale Realized Variance (TSRV) — Zhang, Mykland & Aït-Sahalia (2005).
+ *
+ * Plain realized variance is biased upward by microstructure noise, and sparse
+ * (subsampled) realized variance reduces that bias but doesn't remove it. TSRV
+ * removes it: it combines two sampling scales — a slow, subsampled RV and the
+ * fast all-ticks RV (which is essentially a pure measurement of the noise) — and
+ * subtracts a bias correction, yielding a *consistent* estimator of integrated
+ * variance that uses every observation.
+ *
+ *   TSRV = (1 − n̄/n)⁻¹ · ( RV_sparse(K) − (n̄/n) · RV_all )
+ *
+ * where RV_all is the finest-grid Σrᵢ², RV_sparse(K) is realized variance on a
+ * grid K times coarser averaged over all K offsets (subsampling), and
+ * n̄ = (n − K + 1)/K is the average number of returns per slow subgrid. The
+ * leading factor is the small-sample bias adjustment. `K` (the slow scale) is
+ * best read off a volatility signature plot (see the `noise` module).
+ */
+
+import { sparseRealizedVariance } from "./noise.ts";
+
+function realizedVarAll(returns: readonly number[]): number {
+  let s = 0;
+  for (const r of returns) s += r * r;
+  return s;
+}
+
+/**
+ * Two-scale realized variance: a microstructure-noise-consistent estimator of
+ * integrated variance. `slowScale` (K ≥ 2) is the coarse sampling factor.
+ * Returns plain realized variance for `slowScale < 2` (no second scale) and 0
+ * for fewer than two returns. In heavy-noise / very-small-sample cases the
+ * estimate can be slightly negative, like any bias-corrected variance
+ * estimator; floor it yourself if you need a non-negative value.
+ */
+export function twoScaleRealizedVariance(
+  returns: readonly number[],
+  slowScale: number,
+): number {
+  const n = returns.length;
+  const k = Math.floor(slowScale);
+  if (n < 2) return 0;
+  if (k < 2) return realizedVarAll(returns);
+
+  const rvSparse = sparseRealizedVariance(returns, k);
+  const rvAll = realizedVarAll(returns);
+  const nBar = (n - k + 1) / k;
+  const adj = 1 - nBar / n;
+  if (adj <= 0) return rvSparse; // too few observations for the correction
+  return (rvSparse - (nBar / n) * rvAll) / adj;
+}
+
+/**
+ * Two-scale realized volatility: the square root of `twoScaleRealizedVariance`,
+ * floored at 0 (a negative small-sample estimate is treated as zero variance).
+ */
+export function twoScaleRealizedVolatility(
+  returns: readonly number[],
+  slowScale: number,
+): number {
+  const v = twoScaleRealizedVariance(returns, slowScale);
+  return Math.sqrt(v > 0 ? v : 0);
+}