orderflow-metrics 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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

package/dist/index.d.ts

@@ -34,6 +34,7 @@ export { bipowerVariation, jumpVariation, relativeJumpVariation, } from "./jumps
 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

@@ -20,6 +20,7 @@ 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,aAAa,EACb,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,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/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.26.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), 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

@@ -70,6 +70,10 @@ export {
   sparseRealizedVariance,
   volatilitySignature,
 } from "./noise.ts";
+export {
+  twoScaleRealizedVariance,
+  twoScaleRealizedVolatility,
+} from "./tsrv.ts";
 export type { Semivariance } from "./semivar.ts";
 export {
   realizedSemivariance,

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);
+}