garch 1.0.3 → 1.2.0

package/build/index.mjs

@@ -9,7 +9,7 @@ function nelderMead(fn, x0, options = {}) {
     const simplex = [x0.slice()];
     for (let i = 0; i < n; i++) {
         const point = x0.slice();
-        const delta = point[i] === 0 ? 0.00025 : point[i] * 0.05;
+        const delta = point[i] === 0 ? 0.00025 : point[i] * 0.20;
         point[i] += delta;
         simplex.push(point);
     }
@@ -103,6 +103,38 @@ function shrink(simplex, values, sigma, fn, n) {
         values[i] = fn(simplex[i]);
     }
 }
+/**
+ * Multi-start Nelder-Mead: runs NM from multiple deterministic starting
+ * points and returns the best result. Escapes local minima by exploring
+ * different basins of attraction.
+ *
+ * Perturbation uses golden-ratio quasi-random sequence for uniform
+ * coverage of the search space without clustering.
+ */
+const PHI = (1 + Math.sqrt(5)) / 2; // golden ratio
+function nelderMeadMultiStart(fn, x0, options = {}) {
+    const { maxIter = 1000, tol = 1e-8, restarts = 3 } = options;
+    const n = x0.length;
+    // Run from original starting point
+    let best = nelderMead(fn, x0, { maxIter, tol });
+    // Run from perturbed starting points
+    for (let k = 1; k <= restarts; k++) {
+        const perturbed = new Array(n);
+        for (let i = 0; i < n; i++) {
+            // Quasi-random perturbation: golden-ratio sequence mapped to [-0.5, +0.5]
+            const frac = (k * (i + 1) * PHI) % 1;
+            const scale = frac - 0.5; // range [-0.5, +0.5]
+            perturbed[i] = x0[i] === 0
+                ? 0.001 * scale
+                : x0[i] * (1 + scale);
+        }
+        const result = nelderMead(fn, perturbed, { maxIter, tol });
+        if (result.fx < best.fx) {
+            best = result;
+        }
+    }
+    return best;
+}
 
 /**
  * Calculate log returns from candles
@@ -223,6 +255,26 @@ function yangZhangVariance(candles) {
     const rsVar = rsSum / count;
     return overnightVar + k * closeVar + (1 - k) * rsVar;
 }
+/**
+ * Per-candle Parkinson (1980) realized variance proxy.
+ *
+ * RV_i = (1/(4·ln2)) · ln(H/L)²
+ *
+ * ~5× more efficient than squared returns. Falls back to r² when H === L.
+ * rv[i] aligned with returns[i], using candles[i+1]'s OHLC.
+ */
+function perCandleParkinson(candles, returns) {
+    const coeff = 1 / (4 * Math.LN2);
+    const rv = [];
+    for (let i = 0; i < returns.length; i++) {
+        const c = candles[i + 1];
+        const hl = Math.log(c.high / c.low);
+        const parkinson = coeff * hl * hl;
+        // Fall back to r² if high === low (zero range)
+        rv.push(parkinson > 0 ? parkinson : returns[i] * returns[i]);
+    }
+    return rv;
+}
 /**
  * Expected value of |Z| where Z ~ N(0,1)
  * E[|Z|] = sqrt(2/π)
@@ -276,6 +328,96 @@ function ljungBox(data, maxLag) {
     Q *= n * (n + 2);
     return { statistic: Q, pValue: chi2Survival(Q, maxLag) };
 }
+// ── Student-t distribution helpers ─────────────────────────────
+/**
+ * Log-Gamma function via Lanczos approximation (g=7, n=9).
+ * Accurate to ~15 digits for x > 0.
+ */
+function logGamma(x) {
+    if (x <= 0)
+        return Infinity;
+    const g = 7;
+    const c = [
+        0.99999999999980993,
+        676.5203681218851,
+        -1259.1392167224028,
+        771.32342877765313,
+        -176.6150291621406,
+        12.507343278686905,
+        -0.13857109526572012,
+        9.9843695780195716e-6,
+        1.5056327351493116e-7,
+    ];
+    let sum = c[0];
+    for (let i = 1; i < g + 2; i++) {
+        sum += c[i] / (x - 1 + i);
+    }
+    const t = x - 1 + g + 0.5;
+    return 0.5 * Math.log(2 * Math.PI) + (x - 0.5) * Math.log(t) - t + Math.log(sum);
+}
+/**
+ * Per-observation Student-t negative log-likelihood contribution.
+ *
+ * For standardized t(df) with variance σ²_t:
+ *   -LL_i = 0.5·ln(σ²_t) + ((df+1)/2)·ln(1 + r²_t / ((df-2)·σ²_t))
+ *         - lnΓ((df+1)/2) + lnΓ(df/2) + 0.5·ln(π·(df-2))
+ *
+ * Returns the per-observation neg-LL (without the constant terms).
+ * Caller accumulates and adds the constant once.
+ */
+function studentTNegLL(returns, varianceSeries, df) {
+    const n = returns.length;
+    // Constant part (same for all observations)
+    const halfDfPlus1 = (df + 1) / 2;
+    const constant = n * (logGamma(df / 2) - logGamma(halfDfPlus1) + 0.5 * Math.log(Math.PI * (df - 2)));
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+        const v = varianceSeries[i];
+        if (v <= 1e-12 || !isFinite(v))
+            return 1e10;
+        sum += 0.5 * Math.log(v) + halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / ((df - 2) * v));
+    }
+    return sum + constant;
+}
+/**
+ * E[|Z|] where Z follows a standardized Student-t(df) distribution (variance = 1).
+ *
+ * E[|Z|] = √((df-2)/π) · Γ((df-1)/2) / Γ(df/2)
+ *
+ * Converges to √(2/π) as df → ∞ (Gaussian limit).
+ */
+function expectedAbsStudentT(df) {
+    if (df <= 2)
+        return EXPECTED_ABS_NORMAL; // fallback
+    return Math.sqrt((df - 2) / Math.PI) * Math.exp(logGamma((df - 1) / 2) - logGamma(df / 2));
+}
+/**
+ * 1D grid search for optimal df that minimizes Student-t neg-LL.
+ * Used by HAR-RV and NoVaS where df is profiled after main optimization.
+ */
+function profileStudentTDf(returns, varianceSeries) {
+    let bestDf = 30;
+    let bestNLL = studentTNegLL(returns, varianceSeries, 30);
+    // Coarse grid: 2.5 to 50
+    for (let df = 2.5; df <= 50; df += 0.5) {
+        const nll = studentTNegLL(returns, varianceSeries, df);
+        if (nll < bestNLL) {
+            bestNLL = nll;
+            bestDf = df;
+        }
+    }
+    // Fine grid around best
+    const lo = Math.max(2.1, bestDf - 1);
+    const hi = bestDf + 1;
+    for (let df = lo; df <= hi; df += 0.05) {
+        const nll = studentTNegLL(returns, varianceSeries, df);
+        if (nll < bestNLL) {
+            bestNLL = nll;
+            bestDf = df;
+        }
+    }
+    return bestDf;
+}
 /**
  * Calculate AIC (Akaike Information Criterion)
  */
@@ -288,6 +430,83 @@ function calculateAIC(logLikelihood, numParams) {
 function calculateBIC(logLikelihood, numParams, numObs) {
     return numParams * Math.log(numObs) - 2 * logLikelihood;
 }
+/**
+ * QLIKE loss (Patton 2011) — standard loss function for volatility forecasts.
+ *
+ * QLIKE = (1/n) · Σ (RV_t / σ²_t − log(RV_t / σ²_t) − 1)
+ *
+ * Lower = better forecast. Neutral to calibration method — judges only
+ * how well the variance series predicts realized variance, regardless
+ * of how the model was calibrated (MLE, OLS, D², etc.).
+ */
+function qlike(varianceSeries, rv) {
+    const n = Math.min(varianceSeries.length, rv.length);
+    let sum = 0;
+    let count = 0;
+    for (let i = 0; i < n; i++) {
+        if (varianceSeries[i] <= 0 || rv[i] <= 0)
+            continue;
+        const ratio = rv[i] / varianceSeries[i];
+        sum += ratio - Math.log(ratio) - 1;
+        count++;
+    }
+    return count > 0 ? sum / count : Infinity;
+}
+/**
+ * Inverse standard normal CDF (probit function).
+ * Converts a two-sided confidence level (e.g. 0.95) to the corresponding
+ * z-score (e.g. 1.96).
+ *
+ * Uses Acklam's rational approximation (max relative error < 1.15e-9).
+ */
+function probit(confidence) {
+    if (confidence <= 0 || confidence >= 1) {
+        throw new Error(`confidence must be in (0, 1), got ${confidence}`);
+    }
+    // Convert two-sided confidence to upper-tail probability
+    const p = (1 + confidence) / 2;
+    // Acklam's inverse normal approximation
+    const a1 = -39.69683028665376;
+    const a2 = 2.209460984245205e+02;
+    const a3 = -275.9285104469687;
+    const a4 = 1.383577518672690e+02;
+    const a5 = -30.66479806614716;
+    const a6 = 2.506628277459239e+00;
+    const b1 = -54.47609879822406;
+    const b2 = 1.615858368580409e+02;
+    const b3 = -155.6989798598866;
+    const b4 = 6.680131188771972e+01;
+    const b5 = -13.28068155288572;
+    const c1 = -0.007784894002430293;
+    const c2 = -0.3223964580411365;
+    const c3 = -2.400758277161838;
+    const c4 = -2.549732539343734;
+    const c5 = 4.374664141464968e+00;
+    const c6 = 2.938163982698783e+00;
+    const d1 = 7.784695709041462e-03;
+    const d2 = 3.224671290700398e-01;
+    const d3 = 2.445134137142996e+00;
+    const d4 = 3.754408661907416e+00;
+    const pLow = 0.02425;
+    const pHigh = 1 - pLow;
+    let q, r;
+    if (p < pLow) {
+        q = Math.sqrt(-2 * Math.log(p));
+        return (((((c1 * q + c2) * q + c3) * q + c4) * q + c5) * q + c6) /
+            ((((d1 * q + d2) * q + d3) * q + d4) * q + 1);
+    }
+    else if (p <= pHigh) {
+        q = p - 0.5;
+        r = q * q;
+        return (((((a1 * r + a2) * r + a3) * r + a4) * r + a5) * r + a6) * q /
+            (((((b1 * r + b2) * r + b3) * r + b4) * r + b5) * r + 1);
+    }
+    else {
+        q = Math.sqrt(-2 * Math.log(1 - p));
+        return -(((((c1 * q + c2) * q + c3) * q + c4) * q + c5) * q + c6) /
+            ((((d1 * q + d2) * q + d3) * q + d4) * q + 1);
+    }
+}
 
 /**
  * GARCH(1,1) model
@@ -302,6 +521,7 @@ function calculateBIC(logLikelihood, numParams, numObs) {
  */
 class Garch {
     returns;
+    rv;
     periodsPerYear;
     initialVariance;
     constructor(data, options = {}) {
@@ -313,11 +533,14 @@ class Garch {
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
             this.initialVariance = sampleVariance(this.returns);
+            this.rv = null;
         }
         else {
             const candles = data;
             this.returns = calculateReturns(candles);
             this.initialVariance = yangZhangVariance(candles);
+            // Parkinson (1980) per-candle RV: ~5× more efficient than r²
+            this.rv = perCandleParkinson(candles, this.returns);
         }
     }
     /**
@@ -328,9 +551,10 @@ class Garch {
         const returns = this.returns;
         const n = returns.length;
         const initVar = this.initialVariance;
-        // Negative log-likelihood function
+        const rv = this.rv;
+        // Student-t negative log-likelihood function
         function negLogLikelihood(params) {
-            const [omega, alpha, beta] = params;
+            const [omega, alpha, beta, df] = params;
             // Constraints
             if (omega <= 1e-12)
                 return 1e10;
@@ -338,30 +562,37 @@ class Garch {
                 return 1e10;
             if (alpha + beta >= 0.9999)
                 return 1e10;
+            if (df <= 2.01 || df > 100)
+                return 1e10;
+            const halfDfPlus1 = (df + 1) / 2;
+            const dfMinus2 = df - 2;
+            const constant = n * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
             let variance = initVar;
             let ll = 0;
             for (let i = 0; i < n; i++) {
                 if (i > 0) {
-                    variance = omega + alpha * returns[i - 1] ** 2 + beta * variance;
+                    const innovation = rv ? rv[i - 1] : returns[i - 1] ** 2;
+                    variance = omega + alpha * innovation + beta * variance;
                 }
                 if (variance <= 1e-12)
                     return 1e10;
-                // Gaussian log-likelihood (dropping constant)
-                ll += Math.log(variance) + (returns[i] ** 2) / variance;
+                // Student-t log-likelihood
+                ll += -0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance));
             }
-            return ll / 2;
+            return -(ll + constant);
         }
         // Initial guesses
         const omega0 = initVar * 0.05;
         const alpha0 = 0.1;
         const beta0 = 0.85;
-        const result = nelderMead(negLogLikelihood, [omega0, alpha0, beta0], { maxIter, tol });
-        const [omega, alpha, beta] = result.x;
+        const df0 = 5;
+        const result = nelderMeadMultiStart(negLogLikelihood, [omega0, alpha0, beta0, df0], { maxIter, tol, restarts: 3 });
+        const [omega, alpha, beta, df] = result.x;
         const persistence = alpha + beta;
         const unconditionalVariance = omega / (1 - persistence);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
         const logLikelihood = -result.fx;
-        const numParams = 3;
+        const numParams = 4;
         return {
             params: {
                 omega,
@@ -370,6 +601,7 @@ class Garch {
                 persistence,
                 unconditionalVariance,
                 annualizedVol,
+                df,
             },
             diagnostics: {
                 logLikelihood,
@@ -391,7 +623,8 @@ class Garch {
                 variance.push(this.initialVariance);
             }
             else {
-                const v = omega + alpha * this.returns[i - 1] ** 2 + beta * variance[i - 1];
+                const innovation = this.rv ? this.rv[i - 1] : this.returns[i - 1] ** 2;
+                const v = omega + alpha * innovation + beta * variance[i - 1];
                 variance.push(v);
             }
         }
@@ -406,9 +639,11 @@ class Garch {
         // Get last variance
         const varianceSeries = this.getVarianceSeries(params);
         const lastVariance = varianceSeries[varianceSeries.length - 1];
-        const lastReturn = this.returns[this.returns.length - 1];
+        const lastInnovation = this.rv
+            ? this.rv[this.rv.length - 1]
+            : this.returns[this.returns.length - 1] ** 2;
         // One-step ahead
-        let v = omega + alpha * lastReturn ** 2 + beta * lastVariance;
+        let v = omega + alpha * lastInnovation + beta * lastVariance;
         variance.push(v);
         // Multi-step ahead (converges to unconditional variance)
         for (let h = 1; h < steps; h++) {
@@ -453,10 +688,11 @@ function calibrateGarch(data, options = {}) {
  * - α (alpha): magnitude effect
  * - γ (gamma): leverage effect (typically negative)
  * - β (beta): persistence
- * - E[|z|] = √(2/π) for standard normal
+ * - E[|z|] = expectedAbsStudentT(df) for Student-t(df)
  */
 class Egarch {
     returns;
+    rv;
     periodsPerYear;
     initialVariance;
     constructor(data, options = {}) {
@@ -467,11 +703,14 @@ class Egarch {
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
             this.initialVariance = sampleVariance(this.returns);
+            this.rv = null;
         }
         else {
             const candles = data;
             this.returns = calculateReturns(candles);
             this.initialVariance = yangZhangVariance(candles);
+            // Parkinson (1980) per-candle RV: ~5× more efficient than r²
+            this.rv = perCandleParkinson(candles, this.returns);
         }
     }
     /**
@@ -482,20 +721,31 @@ class Egarch {
         const returns = this.returns;
         const n = returns.length;
         const initLogVar = Math.log(this.initialVariance);
+        const rv = this.rv;
         function negLogLikelihood(params) {
-            const [omega, alpha, gamma, beta] = params;
+            const [omega, alpha, gamma, beta, df] = params;
             // EGARCH allows negative gamma, but beta should ensure stationarity
             if (Math.abs(beta) >= 0.9999)
                 return 1e10;
+            if (df <= 2.01 || df > 100)
+                return 1e10;
+            const eAbsZ = expectedAbsStudentT(df);
+            const halfDfPlus1 = (df + 1) / 2;
+            const dfMinus2 = df - 2;
+            const constant = n * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
             let logVariance = initLogVar;
             let variance = Math.exp(logVariance);
             let ll = 0;
             for (let i = 0; i < n; i++) {
                 if (i > 0) {
                     const sigma = Math.sqrt(variance);
-                    const z = returns[i - 1] / sigma;
+                    const z = returns[i - 1] / sigma; // directional — kept for leverage
+                    // Magnitude: √(RV/σ²) for candles, |z| for prices
+                    const magnitude = rv
+                        ? Math.sqrt(rv[i - 1] / variance)
+                        : Math.abs(z);
                     logVariance = omega
-                        + alpha * (Math.abs(z) - EXPECTED_ABS_NORMAL)
+                        + alpha * (magnitude - eAbsZ)
                         + gamma * z
                         + beta * logVariance;
                     // Prevent extreme values
@@ -504,9 +754,10 @@ class Egarch {
                 }
                 if (variance <= 1e-12 || !isFinite(variance))
                     return 1e10;
-                ll += Math.log(variance) + (returns[i] ** 2) / variance;
+                // Student-t log-likelihood
+                ll += -0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance));
             }
-            return ll / 2;
+            return -(ll + constant);
         }
         // Initial guesses
         // omega approximates log of unconditional variance when other params are small
@@ -514,15 +765,16 @@ class Egarch {
         const alpha0 = 0.1;
         const gamma0 = -0.05; // Negative for typical leverage effect
         const beta0 = 0.95;
-        const result = nelderMead(negLogLikelihood, [omega0, alpha0, gamma0, beta0], { maxIter, tol });
-        const [omega, alpha, gamma, beta] = result.x;
+        const df0 = 5;
+        const result = nelderMeadMultiStart(negLogLikelihood, [omega0, alpha0, gamma0, beta0, df0], { maxIter, tol, restarts: 4 });
+        const [omega, alpha, gamma, beta, df] = result.x;
         // For EGARCH, unconditional variance: E[ln(σ²)] = ω/(1-β)
         // So E[σ²] ≈ exp(ω/(1-β)) when α and γ effects average out
         const unconditionalLogVar = omega / (1 - beta);
         const unconditionalVariance = Math.exp(unconditionalLogVar);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
         const logLikelihood = -result.fx;
-        const numParams = 4;
+        const numParams = 5;
         return {
             params: {
                 omega,
@@ -533,6 +785,7 @@ class Egarch {
                 unconditionalVariance,
                 annualizedVol,
                 leverageEffect: gamma,
+                df,
             },
             diagnostics: {
                 logLikelihood,
@@ -547,7 +800,8 @@ class Egarch {
      * Calculate conditional variance series given parameters
      */
     getVarianceSeries(params) {
-        const { omega, alpha, gamma, beta } = params;
+        const { omega, alpha, gamma, beta, df } = params;
+        const eAbsZ = df > 2 ? expectedAbsStudentT(df) : EXPECTED_ABS_NORMAL;
         const variance = [];
         let logVariance = Math.log(this.initialVariance);
         for (let i = 0; i < this.returns.length; i++) {
@@ -557,8 +811,11 @@ class Egarch {
             else {
                 const sigma = Math.sqrt(variance[i - 1]);
                 const z = this.returns[i - 1] / sigma;
+                const magnitude = this.rv
+                    ? Math.sqrt(this.rv[i - 1] / variance[i - 1])
+                    : Math.abs(z);
                 logVariance = omega
-                    + alpha * (Math.abs(z) - EXPECTED_ABS_NORMAL)
+                    + alpha * (magnitude - eAbsZ)
                     + gamma * z
                     + beta * logVariance;
                 logVariance = Math.max(-50, Math.min(50, logVariance));
@@ -575,7 +832,8 @@ class Egarch {
      * expected values of future shocks.
      */
     forecast(params, steps = 1) {
-        const { omega, alpha, gamma, beta } = params;
+        const { omega, alpha, gamma, beta, df } = params;
+        const eAbsZ = df > 2 ? expectedAbsStudentT(df) : EXPECTED_ABS_NORMAL;
         const variance = [];
         const varianceSeries = this.getVarianceSeries(params);
         const lastVariance = varianceSeries[varianceSeries.length - 1];
@@ -583,12 +841,15 @@ class Egarch {
         // One-step ahead using actual last return
         const sigma = Math.sqrt(lastVariance);
         const z = lastReturn / sigma;
+        const magnitude = this.rv
+            ? Math.sqrt(this.rv[this.rv.length - 1] / lastVariance)
+            : Math.abs(z);
         let logVariance = omega
-            + alpha * (Math.abs(z) - EXPECTED_ABS_NORMAL)
+            + alpha * (magnitude - eAbsZ)
             + gamma * z
             + beta * Math.log(lastVariance);
         variance.push(Math.exp(logVariance));
-        // Multi-step: assume E[z] = 0, E[|z|] = √(2/π)
+        // Multi-step: assume E[z] = 0, E[|z|] = eAbsZ
         // So the α and γ terms contribute 0 on average
         for (let h = 1; h < steps; h++) {
             logVariance = omega + beta * logVariance;
@@ -621,6 +882,723 @@ function calibrateEgarch(data, options = {}) {
     return model.fit(options);
 }
 
+const DEFAULT_SHORT = 1;
+const DEFAULT_MEDIUM = 5;
+const DEFAULT_LONG = 22;
+/**
+ * Solve linear system Ax = b via Gaussian elimination with partial pivoting.
+ * A is n×n, b is n-vector. Returns x.
+ */
+function solveLinearSystem(A, b) {
+    const n = A.length;
+    const M = A.map((row, i) => [...row, b[i]]);
+    for (let col = 0; col < n; col++) {
+        let maxRow = col;
+        let maxVal = Math.abs(M[col][col]);
+        for (let row = col + 1; row < n; row++) {
+            if (Math.abs(M[row][col]) > maxVal) {
+                maxVal = Math.abs(M[row][col]);
+                maxRow = row;
+            }
+        }
+        [M[col], M[maxRow]] = [M[maxRow], M[col]];
+        if (Math.abs(M[col][col]) < 1e-15) {
+            throw new Error('Singular matrix in HAR-RV OLS');
+        }
+        for (let row = col + 1; row < n; row++) {
+            const factor = M[row][col] / M[col][col];
+            for (let j = col; j <= n; j++) {
+                M[row][j] -= factor * M[col][j];
+            }
+        }
+    }
+    const x = new Array(n).fill(0);
+    for (let i = n - 1; i >= 0; i--) {
+        x[i] = M[i][n];
+        for (let j = i + 1; j < n; j++) {
+            x[i] -= M[i][j] * x[j];
+        }
+        x[i] /= M[i][i];
+    }
+    return x;
+}
+/**
+ * OLS regression: y = Xβ + ε
+ * Returns coefficients, residuals, R², RSS, TSS.
+ */
+function ols(X, y) {
+    const n = X.length;
+    const p = X[0].length;
+    // X'X
+    const XtX = Array.from({ length: p }, () => new Array(p).fill(0));
+    for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+            for (let k = 0; k < n; k++) {
+                XtX[i][j] += X[k][i] * X[k][j];
+            }
+        }
+    }
+    // X'y
+    const Xty = new Array(p).fill(0);
+    for (let i = 0; i < p; i++) {
+        for (let k = 0; k < n; k++) {
+            Xty[i] += X[k][i] * y[k];
+        }
+    }
+    const beta = solveLinearSystem(XtX, Xty);
+    const yMean = y.reduce((s, v) => s + v, 0) / n;
+    let rss = 0;
+    let tss = 0;
+    const residuals = [];
+    for (let i = 0; i < n; i++) {
+        let yHat = 0;
+        for (let j = 0; j < p; j++) {
+            yHat += X[i][j] * beta[j];
+        }
+        const res = y[i] - yHat;
+        residuals.push(res);
+        rss += res * res;
+        tss += (y[i] - yMean) ** 2;
+    }
+    const r2 = tss > 0 ? 1 - rss / tss : 0;
+    return { beta, residuals, rss, tss, r2 };
+}
+/**
+ * Compute rolling mean of rv[t-lag+1 .. t] (inclusive).
+ */
+function rollingMean(rv, t, lag) {
+    let sum = 0;
+    for (let j = 0; j < lag; j++) {
+        sum += rv[t - j];
+    }
+    return sum / lag;
+}
+/**
+ * HAR-RV model (Corsi, 2009)
+ *
+ * RV_{t+1} = β₀ + β₁·RV_short + β₂·RV_medium + β₃·RV_long + ε
+ *
+ * where:
+ * - RV_short  = mean(rv[t-s+1..t])  (default s=1)
+ * - RV_medium = mean(rv[t-m+1..t])  (default m=5)
+ * - RV_long   = mean(rv[t-l+1..t])  (default l=22)
+ * - rv[t] = Parkinson(candle_t) for OHLC data, r[t]² for prices-only
+ *
+ * Parkinson (1980): RV = (1/(4·ln2))·(ln(H/L))², ~5x more efficient than r².
+ *
+ * Uses OLS for estimation — closed-form, always converges.
+ */
+class HarRv {
+    returns;
+    rv;
+    periodsPerYear;
+    shortLag;
+    mediumLag;
+    longLag;
+    constructor(data, options = {}) {
+        this.periodsPerYear = options.periodsPerYear ?? 252;
+        this.shortLag = options.shortLag ?? DEFAULT_SHORT;
+        this.mediumLag = options.mediumLag ?? DEFAULT_MEDIUM;
+        this.longLag = options.longLag ?? DEFAULT_LONG;
+        const minRequired = this.longLag + 30;
+        if (data.length < minRequired) {
+            throw new Error(`Need at least ${minRequired} data points for HAR-RV estimation`);
+        }
+        if (typeof data[0] === 'number') {
+            this.returns = calculateReturnsFromPrices(data);
+            // Prices only — no OHLC, fall back to squared returns
+            this.rv = this.returns.map(r => r * r);
+        }
+        else {
+            const candles = data;
+            this.returns = calculateReturns(candles);
+            // Parkinson (1980) per-candle RV: (1/(4·ln2))·(ln(H/L))²
+            this.rv = perCandleParkinson(candles, this.returns);
+        }
+    }
+    /**
+     * Calibrate HAR-RV via OLS.
+     */
+    fit() {
+        const { rv, shortLag, mediumLag, longLag } = this;
+        const n = rv.length;
+        // Build regression data
+        // Usable range: t = longLag-1 .. n-2 (need longLag history, and rv[t+1] as target)
+        const startIdx = longLag - 1;
+        const endIdx = n - 2;
+        const nObs = endIdx - startIdx + 1;
+        const X = [];
+        const y = [];
+        for (let t = startIdx; t <= endIdx; t++) {
+            const rvShort = rollingMean(rv, t, shortLag);
+            const rvMedium = rollingMean(rv, t, mediumLag);
+            const rvLong = rollingMean(rv, t, longLag);
+            X.push([1, rvShort, rvMedium, rvLong]);
+            y.push(rv[t + 1]);
+        }
+        const result = ols(X, y);
+        const [beta0, betaShort, betaMedium, betaLong] = result.beta;
+        const persistence = betaShort + betaMedium + betaLong;
+        const unconditionalVariance = persistence < 1 && persistence > -1
+            ? Math.max(beta0 / (1 - persistence), 1e-20)
+            : sampleVariance(this.returns);
+        const annualizedVol = Math.sqrt(Math.abs(unconditionalVariance) * this.periodsPerYear) * 100;
+        // Student-t log-likelihood on returns using HAR-RV fitted variances
+        const varianceSeries = this.getVarianceSeriesInternal(result.beta);
+        const df = profileStudentTDf(this.returns, varianceSeries);
+        const ll = -studentTNegLL(this.returns, varianceSeries, df);
+        const numParams = 5; // beta0, betaShort, betaMedium, betaLong, df
+        return {
+            params: {
+                beta0,
+                betaShort,
+                betaMedium,
+                betaLong,
+                persistence,
+                unconditionalVariance,
+                annualizedVol,
+                r2: result.r2,
+                df,
+            },
+            diagnostics: {
+                logLikelihood: ll,
+                aic: calculateAIC(ll, numParams),
+                bic: calculateBIC(ll, numParams, nObs),
+                iterations: 1,
+                converged: true,
+            },
+        };
+    }
+    /**
+     * Internal: compute variance series from beta vector.
+     */
+    getVarianceSeriesInternal(beta) {
+        const { rv, shortLag, mediumLag, longLag } = this;
+        const n = rv.length;
+        const fallback = sampleVariance(this.returns);
+        const series = [];
+        for (let i = 0; i < n; i++) {
+            if (i < longLag) {
+                // Not enough history — use sample variance
+                series.push(fallback);
+            }
+            else {
+                // HAR prediction for rv[i] based on rv[..i-1]
+                const t = i - 1;
+                const rvS = rollingMean(rv, t, shortLag);
+                const rvM = rollingMean(rv, t, mediumLag);
+                const rvL = rollingMean(rv, t, longLag);
+                const predicted = beta[0] + beta[1] * rvS + beta[2] * rvM + beta[3] * rvL;
+                series.push(Math.max(predicted, 1e-20));
+            }
+        }
+        return series;
+    }
+    /**
+     * Calculate conditional variance series given parameters.
+     */
+    getVarianceSeries(params) {
+        const beta = [params.beta0, params.betaShort, params.betaMedium, params.betaLong];
+        return this.getVarianceSeriesInternal(beta);
+    }
+    /**
+     * Forecast variance forward.
+     *
+     * Uses iterative substitution: each forecast step feeds back
+     * into the rolling RV components for subsequent steps.
+     */
+    forecast(params, steps = 1) {
+        const { rv, shortLag, mediumLag, longLag } = this;
+        const { beta0, betaShort, betaMedium, betaLong } = params;
+        // Working copy of recent rv values + forecasts appended
+        const history = rv.slice();
+        const variance = [];
+        for (let h = 0; h < steps; h++) {
+            const t = history.length - 1;
+            const rvS = rollingMean(history, t, shortLag);
+            const rvM = rollingMean(history, t, mediumLag);
+            const rvL = rollingMean(history, t, longLag);
+            const predicted = beta0 + betaShort * rvS + betaMedium * rvM + betaLong * rvL;
+            const v = Math.max(predicted, 1e-20);
+            variance.push(v);
+            history.push(v);
+        }
+        return {
+            variance,
+            volatility: variance.map(v => Math.sqrt(v)),
+            annualized: variance.map(v => Math.sqrt(v * this.periodsPerYear) * 100),
+        };
+    }
+    /**
+     * Get the return series.
+     */
+    getReturns() {
+        return [...this.returns];
+    }
+    /**
+     * Get realized variance series (squared returns).
+     */
+    getRv() {
+        return [...this.rv];
+    }
+}
+/**
+ * Convenience function to calibrate HAR-RV from candles or prices.
+ */
+function calibrateHarRv(data, options = {}) {
+    const model = new HarRv(data, options);
+    return model.fit();
+}
+
+/**
+ * GJR-GARCH(1,1) model (Glosten, Jagannathan & Runkle, 1993)
+ *
+ * σ²ₜ = ω + α·ε²ₜ₋₁ + γ·ε²ₜ₋₁·I(rₜ₋₁<0) + β·σ²ₜ₋₁
+ *
+ * where:
+ * - ω (omega) > 0: constant term
+ * - α (alpha) ≥ 0: symmetric shock response
+ * - γ (gamma) ≥ 0: asymmetric leverage coefficient
+ * - β (beta) ≥ 0: persistence
+ * - I(r<0) = 1 when return is negative, 0 otherwise
+ * - Stationarity: α + γ/2 + β < 1
+ *
+ * With Candle[] input, ε² is replaced by Parkinson per-candle RV.
+ * Leverage direction still comes from close-to-close return sign.
+ */
+class GjrGarch {
+    returns;
+    rv;
+    periodsPerYear;
+    initialVariance;
+    constructor(data, options = {}) {
+        this.periodsPerYear = options.periodsPerYear ?? 252;
+        if (data.length < 50) {
+            throw new Error('Need at least 50 data points for GJR-GARCH estimation');
+        }
+        if (typeof data[0] === 'number') {
+            this.returns = calculateReturnsFromPrices(data);
+            this.initialVariance = sampleVariance(this.returns);
+            this.rv = null;
+        }
+        else {
+            const candles = data;
+            this.returns = calculateReturns(candles);
+            this.initialVariance = yangZhangVariance(candles);
+            this.rv = perCandleParkinson(candles, this.returns);
+        }
+    }
+    /**
+     * Calibrate GJR-GARCH(1,1) parameters using Maximum Likelihood Estimation
+     */
+    fit(options = {}) {
+        const { maxIter = 1000, tol = 1e-8 } = options;
+        const returns = this.returns;
+        const n = returns.length;
+        const initVar = this.initialVariance;
+        const rv = this.rv;
+        function negLogLikelihood(params) {
+            const [omega, alpha, gamma, beta, df] = params;
+            if (omega <= 1e-12)
+                return 1e10;
+            if (alpha < 0 || gamma < 0 || beta < 0)
+                return 1e10;
+            if (alpha + gamma / 2 + beta >= 0.9999)
+                return 1e10;
+            if (df <= 2.01 || df > 100)
+                return 1e10;
+            const halfDfPlus1 = (df + 1) / 2;
+            const dfMinus2 = df - 2;
+            const constant = n * (logGamma(halfDfPlus1) - logGamma(df / 2) - 0.5 * Math.log(Math.PI * dfMinus2));
+            let variance = initVar;
+            let ll = 0;
+            for (let i = 0; i < n; i++) {
+                if (i > 0) {
+                    const innovation = rv ? rv[i - 1] : returns[i - 1] ** 2;
+                    const indicator = returns[i - 1] < 0 ? 1 : 0;
+                    variance = omega + alpha * innovation + gamma * innovation * indicator + beta * variance;
+                }
+                if (variance <= 1e-12)
+                    return 1e10;
+                // Student-t log-likelihood
+                ll += -0.5 * Math.log(variance) - halfDfPlus1 * Math.log(1 + (returns[i] ** 2) / (dfMinus2 * variance));
+            }
+            return -(ll + constant);
+        }
+        const omega0 = initVar * 0.05;
+        const alpha0 = 0.05;
+        const gamma0 = 0.1;
+        const beta0 = 0.85;
+        const df0 = 5;
+        const result = nelderMeadMultiStart(negLogLikelihood, [omega0, alpha0, gamma0, beta0, df0], { maxIter, tol, restarts: 4 });
+        const [omega, alpha, gamma, beta, df] = result.x;
+        const persistence = alpha + gamma / 2 + beta;
+        const unconditionalVariance = omega / (1 - persistence);
+        const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
+        const logLikelihood = -result.fx;
+        const numParams = 5;
+        return {
+            params: {
+                omega,
+                alpha,
+                gamma,
+                beta,
+                persistence,
+                unconditionalVariance,
+                annualizedVol,
+                leverageEffect: gamma,
+                df,
+            },
+            diagnostics: {
+                logLikelihood,
+                aic: calculateAIC(logLikelihood, numParams),
+                bic: calculateBIC(logLikelihood, numParams, n),
+                iterations: result.iterations,
+                converged: result.converged,
+            },
+        };
+    }
+    /**
+     * Calculate conditional variance series given parameters
+     */
+    getVarianceSeries(params) {
+        const { omega, alpha, gamma, beta } = params;
+        const variance = [];
+        for (let i = 0; i < this.returns.length; i++) {
+            if (i === 0) {
+                variance.push(this.initialVariance);
+            }
+            else {
+                const innovation = this.rv ? this.rv[i - 1] : this.returns[i - 1] ** 2;
+                const indicator = this.returns[i - 1] < 0 ? 1 : 0;
+                const v = omega + alpha * innovation + gamma * innovation * indicator + beta * variance[i - 1];
+                variance.push(v);
+            }
+        }
+        return variance;
+    }
+    /**
+     * Forecast variance forward
+     */
+    forecast(params, steps = 1) {
+        const { omega, alpha, gamma, beta } = params;
+        const variance = [];
+        const varianceSeries = this.getVarianceSeries(params);
+        const lastVariance = varianceSeries[varianceSeries.length - 1];
+        const lastInnovation = this.rv
+            ? this.rv[this.rv.length - 1]
+            : this.returns[this.returns.length - 1] ** 2;
+        const lastIndicator = this.returns[this.returns.length - 1] < 0 ? 1 : 0;
+        // One-step ahead using actual last return
+        let v = omega + alpha * lastInnovation + gamma * lastInnovation * lastIndicator + beta * lastVariance;
+        variance.push(v);
+        // Multi-step: E[I(r<0)] = 0.5, so effective persistence = α + γ/2 + β
+        for (let h = 1; h < steps; h++) {
+            v = omega + (alpha + gamma / 2 + beta) * v;
+            variance.push(v);
+        }
+        return {
+            variance,
+            volatility: variance.map(v => Math.sqrt(v)),
+            annualized: variance.map(v => Math.sqrt(v * this.periodsPerYear) * 100),
+        };
+    }
+    /**
+     * Get the return series
+     */
+    getReturns() {
+        return [...this.returns];
+    }
+    /**
+     * Get initial variance estimate
+     */
+    getInitialVariance() {
+        return this.initialVariance;
+    }
+}
+/**
+ * Convenience function to calibrate GJR-GARCH(1,1) from candles
+ */
+function calibrateGjrGarch(data, options = {}) {
+    const model = new GjrGarch(data, options);
+    return model.fit(options);
+}
+
+const DEFAULT_LAGS = 10;
+/**
+ * NoVaS (Normalizing and Variance-Stabilizing) model (Politis, 2003)
+ *
+ * Two-stage calibration:
+ *
+ * Stage 1 — D² minimization (model-free normality):
+ *   σ²_t = a_0 + a_1·X²_{t-1} + a_2·X²_{t-2} + ... + a_p·X²_{t-p}
+ *   W_t  = X_t / σ_t
+ *   Minimize D² = S² + (K - 3)² where S, K are skewness and kurtosis of {W_t}.
+ *
+ * Stage 2 — OLS rescaling (forecast-optimal):
+ *   RV_{t+1} = β₀ + β₁·σ²_t(D²)
+ *   The D²-discovered σ²_t acts as a data-driven smoother over RV lags.
+ *   OLS rescales it to minimize forecast error (RSS on RV).
+ *   Only 2 parameters → robust on small samples with noisy per-candle RV.
+ *
+ * D² discovers lag structure (model-free). OLS rescales for prediction accuracy.
+ * Both weight sets are stored in params — no identity loss.
+ */
+class NoVaS {
+    returns;
+    rv;
+    periodsPerYear;
+    lags;
+    constructor(data, options = {}) {
+        this.periodsPerYear = options.periodsPerYear ?? 252;
+        this.lags = options.lags ?? DEFAULT_LAGS;
+        const minRequired = this.lags + 30;
+        if (data.length < minRequired) {
+            throw new Error(`Need at least ${minRequired} data points for NoVaS estimation`);
+        }
+        if (typeof data[0] === 'number') {
+            this.returns = calculateReturnsFromPrices(data);
+            this.rv = null;
+        }
+        else {
+            const candles = data;
+            this.returns = calculateReturns(candles);
+            // Parkinson (1980) per-candle RV: ~5× more efficient than r²
+            this.rv = perCandleParkinson(candles, this.returns);
+        }
+    }
+    /**
+     * Calibrate NoVaS weights via two-stage procedure:
+     * Stage 1: D² minimization (normality of W_t)
+     * Stage 2: OLS rescaling of D²-variance (forecast-optimal)
+     */
+    fit(options = {}) {
+        const { maxIter = 2000, tol = 1e-8 } = options;
+        const returns = this.returns;
+        const n = returns.length;
+        const p = this.lags;
+        const initVar = sampleVariance(returns);
+        // Innovation: Parkinson RV for candles, r² for prices
+        const r2 = this.rv ?? returns.map(r => r * r);
+        /**
+         * Compute D² for a given weight vector.
+         * D² = S² + (K - 3)² where S, K are skewness and kurtosis of W_t.
+         */
+        function objectiveD2(rawWeights) {
+            // Enforce constraints: a_j >= 0 via abs, a_0 > epsilon
+            const weights = rawWeights.map(w => Math.abs(w));
+            if (weights[0] < 1e-15)
+                return 1e10;
+            // Stationarity: sum(a_1..a_p) < 1
+            let lagSum = 0;
+            for (let j = 1; j <= p; j++)
+                lagSum += weights[j];
+            if (lagSum >= 0.9999)
+                return 1e10;
+            // Compute transformed series W_t = r_t / sqrt(sigma^2_t)
+            let sumW = 0;
+            let sumW2 = 0;
+            let sumW3 = 0;
+            let sumW4 = 0;
+            let count = 0;
+            for (let t = p; t < n; t++) {
+                let variance = weights[0];
+                for (let j = 1; j <= p; j++) {
+                    variance += weights[j] * r2[t - j];
+                }
+                if (variance <= 1e-15)
+                    return 1e10;
+                const w = returns[t] / Math.sqrt(variance);
+                if (!isFinite(w))
+                    return 1e10;
+                sumW += w;
+                sumW2 += w * w;
+                sumW3 += w * w * w;
+                sumW4 += w * w * w * w;
+                count++;
+            }
+            if (count < 10)
+                return 1e10;
+            const mean = sumW / count;
+            const m2 = sumW2 / count - mean * mean;
+            if (m2 <= 1e-15)
+                return 1e10;
+            const m3 = sumW3 / count - 3 * mean * sumW2 / count + 2 * mean * mean * mean;
+            const m4 = sumW4 / count - 4 * mean * sumW3 / count
+                + 6 * mean * mean * sumW2 / count - 3 * mean * mean * mean * mean;
+            const skewness = m3 / (m2 * Math.sqrt(m2));
+            const kurtosis = m4 / (m2 * m2);
+            if (!isFinite(skewness) || !isFinite(kurtosis))
+                return 1e10;
+            return skewness * skewness + (kurtosis - 3) * (kurtosis - 3);
+        }
+        // Initial guess: intercept in variance units, lag weights dimensionless
+        const lambda = 0.7;
+        const x0 = [initVar * 0.1];
+        for (let j = 1; j <= p; j++) {
+            x0.push(0.9 * (1 - lambda) * Math.pow(lambda, j - 1));
+        }
+        const result = nelderMeadMultiStart(objectiveD2, x0, { maxIter, tol, restarts: 6 });
+        // Extract final weights (abs for constraint enforcement)
+        const weights = result.x.map(w => Math.abs(w));
+        let persistence = 0;
+        for (let j = 1; j <= p; j++)
+            persistence += weights[j];
+        const unconditionalVariance = persistence < 1 && persistence > -1
+            ? Math.max(weights[0] / (1 - persistence), 1e-20)
+            : sampleVariance(returns);
+        const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
+        // ── Stage 2: OLS rescaling of D²-variance ──────────────
+        // RV_{t+1} = β₀ + β₁·σ²_t(D²)
+        // D² weights discover lag structure; OLS rescales for forecast accuracy.
+        // Only 2 parameters → robust on small samples with noisy per-candle RV.
+        const d2Variance = this.getVarianceSeriesInternal(weights);
+        let forecastWeights;
+        let olsR2;
+        try {
+            let sumX = 0, sumY = 0, sumXX = 0, sumXY = 0, count = 0;
+            for (let t = p; t < n - 1; t++) {
+                const x = d2Variance[t];
+                const y = r2[t + 1];
+                sumX += x;
+                sumY += y;
+                sumXX += x * x;
+                sumXY += x * y;
+                count++;
+            }
+            const denom = count * sumXX - sumX * sumX;
+            if (Math.abs(denom) < 1e-30)
+                throw new Error('Degenerate variance series');
+            const beta1 = (count * sumXY - sumX * sumY) / denom;
+            const beta0 = (sumY - beta1 * sumX) / count;
+            forecastWeights = [beta0, beta1];
+            // R²
+            const yMean = sumY / count;
+            let rss = 0, tss = 0;
+            for (let t = p; t < n - 1; t++) {
+                const yHat = beta0 + beta1 * d2Variance[t];
+                rss += (r2[t + 1] - yHat) ** 2;
+                tss += (r2[t + 1] - yMean) ** 2;
+            }
+            olsR2 = tss > 0 ? 1 - rss / tss : 0;
+        }
+        catch {
+            // OLS failed — fall back to identity rescaling [0, 1]
+            forecastWeights = [0, 1];
+            olsR2 = 0;
+        }
+        // Student-t log-likelihood for AIC comparison with GARCH/EGARCH/HAR-RV
+        const df = profileStudentTDf(returns, d2Variance);
+        const ll = -studentTNegLL(returns, d2Variance, df);
+        const numParams = p + 2; // weights + df
+        const nObs = n - p; // usable observations for D²
+        return {
+            params: {
+                weights,
+                forecastWeights,
+                lags: p,
+                persistence,
+                unconditionalVariance,
+                annualizedVol,
+                dSquared: result.fx,
+                r2: olsR2,
+                df,
+            },
+            diagnostics: {
+                logLikelihood: ll,
+                aic: calculateAIC(ll, numParams),
+                bic: calculateBIC(ll, numParams, nObs),
+                iterations: result.iterations,
+                converged: result.converged,
+            },
+        };
+    }
+    /**
+     * Internal: compute variance series from D² weight vector.
+     */
+    getVarianceSeriesInternal(weights) {
+        const { returns, lags } = this;
+        const n = returns.length;
+        const r2 = this.rv ?? returns.map(r => r * r);
+        const fallback = sampleVariance(returns);
+        const series = [];
+        for (let t = 0; t < n; t++) {
+            if (t < lags) {
+                series.push(fallback);
+            }
+            else {
+                let variance = weights[0];
+                for (let j = 1; j <= lags; j++) {
+                    variance += weights[j] * r2[t - j];
+                }
+                series.push(Math.max(variance, 1e-20));
+            }
+        }
+        return series;
+    }
+    /**
+     * Calculate conditional variance series using D² weights (normalization identity).
+     */
+    getVarianceSeries(params) {
+        return this.getVarianceSeriesInternal(params.weights);
+    }
+    /**
+     * Calculate forecast variance series using OLS-rescaled D² variance.
+     * forecast_σ²_t = β₀ + β₁·σ²_t(D²)
+     * Used for QLIKE model comparison — measures forecast quality.
+     */
+    getForecastVarianceSeries(params) {
+        const d2Series = this.getVarianceSeriesInternal(params.weights);
+        const [beta0, beta1] = params.forecastWeights;
+        return d2Series.map(v => Math.max(beta0 + beta1 * v, 1e-20));
+    }
+    /**
+     * Forecast variance forward using OLS-rescaled D² weights.
+     *
+     * Step 1: compute D²-based σ²_{t+h} using D² weights
+     * Step 2: rescale via β₀ + β₁·σ²_{t+h}
+     */
+    forecast(params, steps = 1) {
+        const { weights, forecastWeights, lags } = params;
+        const [beta0, beta1] = forecastWeights;
+        const r2 = this.rv ?? this.returns.map(r => r * r);
+        // Working buffer: past innovation values + forecasted variances
+        const history = r2.slice();
+        const variance = [];
+        for (let h = 0; h < steps; h++) {
+            const t = history.length;
+            // D²-based variance at this step
+            let d2v = weights[0];
+            for (let j = 1; j <= lags; j++) {
+                d2v += weights[j] * history[t - j];
+            }
+            d2v = Math.max(d2v, 1e-20);
+            // OLS-rescaled forecast
+            const v = Math.max(beta0 + beta1 * d2v, 1e-20);
+            variance.push(v);
+            history.push(v); // future E[RV] = σ²
+        }
+        return {
+            variance,
+            volatility: variance.map(v => Math.sqrt(v)),
+            annualized: variance.map(v => Math.sqrt(v * this.periodsPerYear) * 100),
+        };
+    }
+    /**
+     * Get the return series.
+     */
+    getReturns() {
+        return [...this.returns];
+    }
+}
+/**
+ * Convenience function to calibrate NoVaS from candles or prices.
+ */
+function calibrateNoVaS(data, options = {}) {
+    const model = new NoVaS(data, options);
+    return model.fit(options);
+}
+
 const MIN_CANDLES = {
     '1m': 500,
     '3m': 500,
@@ -633,6 +1611,18 @@ const MIN_CANDLES = {
     '6h': 150,
     '8h': 150,
 };
+const RECOMMENDED_CANDLES = {
+    '1m': 1500,
+    '3m': 1500,
+    '5m': 1500,
+    '15m': 1000,
+    '30m': 1000,
+    '1h': 500,
+    '2h': 500,
+    '4h': 500,
+    '6h': 300,
+    '8h': 300,
+};
 const INTERVALS_PER_YEAR = {
     '1m': 525_600,
     '3m': 175_200,
@@ -650,32 +1640,123 @@ function assertMinCandles(candles, interval) {
     if (candles.length < min) {
         throw new Error(`Need at least ${min} candles for ${interval} interval, got ${candles.length}`);
     }
+    for (let i = 0; i < candles.length; i++) {
+        const c = candles[i];
+        if (!isFinite(c.close) || c.close <= 0) {
+            throw new Error(`Invalid close price at candle ${i}: ${c.close}`);
+        }
+    }
+    const recommended = RECOMMENDED_CANDLES[interval];
+    if (candles.length < recommended) ;
 }
-function fitModel(candles, periodsPerYear, steps) {
-    const returns = calculateReturnsFromPrices(candles.map(c => c.close));
-    const leverage = checkLeverageEffect(returns);
-    if (leverage.recommendation === 'egarch') {
-        const model = new Egarch(candles, { periodsPerYear });
+function fitGarchFamily(candles, periodsPerYear, steps) {
+    // Fit all three GARCH-family models and pick the best by AIC
+    // (AIC is fair here — all three optimize the same Student-t LL)
+    const garchModel = new Garch(candles, { periodsPerYear });
+    const garchFit = garchModel.fit();
+    let bestAic = garchFit.diagnostics.aic;
+    let best = {
+        forecast: garchModel.forecast(garchFit.params, steps),
+        modelType: 'garch',
+        converged: garchFit.diagnostics.converged,
+        persistence: garchFit.params.persistence,
+        varianceSeries: garchModel.getVarianceSeries(garchFit.params),
+        returns: garchModel.getReturns(),
+    };
+    const egarchModel = new Egarch(candles, { periodsPerYear });
+    const egarchFit = egarchModel.fit();
+    if (egarchFit.diagnostics.aic < bestAic) {
+        bestAic = egarchFit.diagnostics.aic;
+        best = {
+            forecast: egarchModel.forecast(egarchFit.params, steps),
+            modelType: 'egarch',
+            converged: egarchFit.diagnostics.converged,
+            persistence: egarchFit.params.persistence,
+            varianceSeries: egarchModel.getVarianceSeries(egarchFit.params),
+            returns: egarchModel.getReturns(),
+        };
+    }
+    const gjrModel = new GjrGarch(candles, { periodsPerYear });
+    const gjrFit = gjrModel.fit();
+    if (gjrFit.diagnostics.aic < bestAic) {
+        best = {
+            forecast: gjrModel.forecast(gjrFit.params, steps),
+            modelType: 'gjr-garch',
+            converged: gjrFit.diagnostics.converged,
+            persistence: gjrFit.params.persistence,
+            varianceSeries: gjrModel.getVarianceSeries(gjrFit.params),
+            returns: gjrModel.getReturns(),
+        };
+    }
+    return best;
+}
+function fitHarRv(candles, periodsPerYear, steps) {
+    try {
+        const model = new HarRv(candles, { periodsPerYear });
         const fit = model.fit();
+        // Skip HAR-RV if persistence >= 1 (non-stationary) or R² too low
+        if (fit.params.persistence >= 1 || fit.params.r2 < 0)
+            return null;
         return {
             forecast: model.forecast(fit.params, steps),
-            modelType: 'egarch',
+            modelType: 'har-rv',
             converged: fit.diagnostics.converged,
             persistence: fit.params.persistence,
             varianceSeries: model.getVarianceSeries(fit.params),
             returns: model.getReturns(),
         };
     }
-    const model = new Garch(candles, { periodsPerYear });
-    const fit = model.fit();
-    return {
-        forecast: model.forecast(fit.params, steps),
-        modelType: 'garch',
-        converged: fit.diagnostics.converged,
-        persistence: fit.params.persistence,
-        varianceSeries: model.getVarianceSeries(fit.params),
-        returns: model.getReturns(),
-    };
+    catch {
+        return null;
+    }
+}
+function fitNoVaS(candles, periodsPerYear, steps) {
+    try {
+        const model = new NoVaS(candles, { periodsPerYear });
+        const fit = model.fit();
+        // Skip if persistence >= 1 (non-stationary)
+        if (fit.params.persistence >= 1)
+            return null;
+        return {
+            forecast: model.forecast(fit.params, steps),
+            modelType: 'novas',
+            converged: fit.diagnostics.converged,
+            persistence: fit.params.persistence,
+            varianceSeries: model.getForecastVarianceSeries(fit.params),
+            returns: model.getReturns(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function fitModel(candles, periodsPerYear, steps) {
+    const garchResult = fitGarchFamily(candles, periodsPerYear, steps);
+    const harResult = fitHarRv(candles, periodsPerYear, steps);
+    const novasResult = fitNoVaS(candles, periodsPerYear, steps);
+    // Compute realized variance (Parkinson RV) for QLIKE scoring
+    const returns = calculateReturns(candles);
+    const rv = perCandleParkinson(candles, returns);
+    // Pick model with lowest QLIKE (Patton 2011) — neutral forecast-error metric.
+    // Unlike AIC (which favors MLE-calibrated models), QLIKE judges only
+    // how well the variance series predicts realized variance.
+    let best = garchResult;
+    let bestScore = qlike(garchResult.varianceSeries, rv);
+    if (harResult) {
+        const score = qlike(harResult.varianceSeries, rv);
+        if (score < bestScore) {
+            best = harResult;
+            bestScore = score;
+        }
+    }
+    if (novasResult) {
+        const score = qlike(novasResult.varianceSeries, rv);
+        if (score < bestScore) {
+            best = novasResult;
+            bestScore = score;
+        }
+    }
+    return best;
 }
 function checkReliable(fit) {
     if (!fit.converged || fit.persistence >= 0.999)
@@ -692,21 +1773,25 @@ function checkReliable(fit) {
 /**
  * Forecast expected price range for t+1 (next candle).
  *
- * Auto-selects GARCH or EGARCH based on leverage effect.
- * Returns ±1σ price corridor so you can set SL/TP yourself.
+ * Auto-selects the best volatility model via QLIKE.
+ * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
+ * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
+ *   Common values: 0.90 → z=1.645, 0.95 → z=1.96, 0.99 → z=2.576.
  */
-function predict(candles, interval, currentPrice = candles[candles.length - 1].close) {
+function predict(candles, interval, currentPrice = candles[candles.length - 1].close, confidence = 0.6827) {
     assertMinCandles(candles, interval);
+    const z = probit(confidence);
     const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], 1);
     const sigma = fit.forecast.volatility[0];
-    const move = currentPrice * sigma;
+    const upperPrice = currentPrice * Math.exp(z * sigma);
+    const lowerPrice = currentPrice * Math.exp(-z * sigma);
     return {
         modelType: fit.modelType,
         currentPrice,
         sigma,
-        move,
-        upperPrice: currentPrice + move,
-        lowerPrice: currentPrice - move,
+        move: upperPrice - currentPrice,
+        upperPrice,
+        lowerPrice,
         reliable: checkReliable(fit),
     };
 }
@@ -714,26 +1799,28 @@ function predict(candles, interval, currentPrice = candles[candles.length - 1].c
  * Forecast expected price range over multiple candles.
  *
  * Cumulative σ = √(σ₁² + σ₂² + ... + σₙ²) — total expected move over N periods.
- * Use for swing trades where you hold across multiple candles.
+ * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
+ * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
  */
-function predictRange(candles, interval, steps, currentPrice = candles[candles.length - 1].close) {
+function predictRange(candles, interval, steps, currentPrice = candles[candles.length - 1].close, confidence = 0.6827) {
     assertMinCandles(candles, interval);
+    const z = probit(confidence);
     const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], steps);
     const cumulativeVariance = fit.forecast.variance.reduce((sum, v) => sum + v, 0);
     const sigma = Math.sqrt(cumulativeVariance);
-    const move = currentPrice * sigma;
+    const upperPrice = currentPrice * Math.exp(z * sigma);
+    const lowerPrice = currentPrice * Math.exp(-z * sigma);
     return {
         modelType: fit.modelType,
         currentPrice,
         sigma,
-        move,
-        upperPrice: currentPrice + move,
-        lowerPrice: currentPrice - move,
+        move: upperPrice - currentPrice,
+        upperPrice,
+        lowerPrice,
         reliable: checkReliable(fit),
     };
 }
 // ── Backtest ──────────────────────────────────────────────────
-const BACKTEST_REQUIRED_PERCENT = 68;
 const BACKTEST_WINDOW_RATIO = 0.75;
 /**
  * Walk-forward backtest of predict.
@@ -741,16 +1828,22 @@ const BACKTEST_WINDOW_RATIO = 0.75;
  * Window is computed automatically: 75% of candles for fitting, 25% for testing.
  * Throws if not enough candles for the given interval.
  * Returns true if the model's hit rate meets the required threshold.
- * Default threshold is 68% (±1σ should contain ~68% of moves).
+ * @param confidence — two-sided probability in (0,1) for the prediction band.
+ *   Default ≈0.6827 (±1σ).
+ * @param requiredPercent — minimum hit rate (0–100) to pass. Default 68.
  */
-function backtest(candles, interval, requiredPercent = BACKTEST_REQUIRED_PERCENT) {
+function backtest(candles, interval, confidence = 0.6827, requiredPercent = 68) {
     assertMinCandles(candles, interval);
+    if (requiredPercent <= 0)
+        return true;
+    if (requiredPercent >= 100)
+        return false;
     const window = Math.max(MIN_CANDLES[interval], Math.floor(candles.length * BACKTEST_WINDOW_RATIO));
     let hits = 0;
     let total = 0;
     for (let i = window; i < candles.length - 1; i++) {
         const slice = candles.slice(i - window, i + 1);
-        const predicted = predict(slice, interval);
+        const predicted = predict(slice, interval, slice[slice.length - 1].close, confidence);
         const actual = candles[i + 1].close;
         if (actual >= predicted.lowerPrice && actual <= predicted.upperPrice) {
             hits++;
@@ -760,4 +1853,4 @@ function backtest(candles, interval, requiredPercent = BACKTEST_REQUIRED_PERCENT
     return (hits / total) * 100 >= requiredPercent;
 }
 
-export { EXPECTED_ABS_NORMAL, Egarch, Garch, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, checkLeverageEffect, garmanKlassVariance, ljungBox, nelderMead, predict, predictRange, sampleVariance, sampleVarianceWithMean, yangZhangVariance };
+export { EXPECTED_ABS_NORMAL, Egarch, Garch, GjrGarch, HarRv, NoVaS, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, checkLeverageEffect, expectedAbsStudentT, garmanKlassVariance, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };