garch 1.1.0 → 1.2.1

package/README.md

@@ -16,9 +16,11 @@ npm install garch
 
 ## API
 
-### `predict(candles, interval, currentPrice?)`
+### `predict(candles, interval, currentPrice?, confidence?)`
 
-Forecast expected price range for the next candle (t+1). Auto-selects the best model (GARCH, EGARCH, GJR-GARCH, HAR-RV or NoVaS) by QLIKE forecast-error comparison. Returns a +-1 sigma price corridor.
+Forecast expected price range for the next candle (t+1). Auto-selects the best model (GARCH, EGARCH, GJR-GARCH, HAR-RV or NoVaS) by QLIKE forecast-error comparison.
+
+Uses **log-normal price bands**: `P·exp(±z·σ)`, where `z = probit(confidence)`. This correctly maps log-return volatility back to price space — the corridor is asymmetric (upside > downside in absolute terms) and `lowerPrice` can never go negative.
 
 ```typescript
 import { predict } from 'garch';
@@ -26,21 +28,50 @@ import type { Candle } from 'garch';
 
 const candles: Candle[] = await fetchCandles('BTCUSDT', '4h', 200);
 
+// Default: ±1σ band (~68% coverage)
 const result = predict(candles, '4h');
 // {
 //   currentPrice: 97500,
-//   sigma: 0.012,          // 1.2% expected move
-//   move: 1170,            // +/-$1170 price range
-//   upperPrice: 98670,     // ceiling for next candle
-//   lowerPrice: 96330,     // floor for next candle
+//   sigma: 0.012,          // 1.2% per-period volatility
+//   move: 1177,            // upward expected move (upper - current)
+//   upperPrice: 98677,     // P·exp(+σ) — ceiling
+//   lowerPrice: 96337,     // P·exp(-σ) — floor
 //   modelType: 'egarch',
 //   reliable: true
 // }
 
-// Pass VWAP or any reference price as 3rd argument
+// 95% VaR band (z ≈ 1.96)
+const var95 = predict(candles, '4h', undefined, 0.95);
+
+// Custom reference price (e.g. VWAP)
 const result = predict(candles, '4h', vwap);
 ```
 
+**Confidence → z mapping:**
+
+| `confidence` | z-score | Meaning |
+|-------------|---------|---------|
+| 0.6827 (default) | 1.00 | ±1σ, ~68% of moves captured |
+| 0.90 | 1.645 | Moderate VaR |
+| 0.95 | 1.96 | 95% VaR (standard) |
+| 0.99 | 2.576 | Conservative VaR |
+
+Any value in (0, 1) is valid — the table above lists common choices, but `probit` computes z for arbitrary confidence.
+
+Higher confidence = wider corridor. `sigma` stays the same (it's the model's volatility estimate), only the z-multiplier changes. Example with sigma=1.2% and P=$97,500:
+
+| `confidence` | z | upperPrice | lowerPrice | Corridor width |
+|-------------|---|-----------|-----------|----------------|
+| 0.6827 | 1.00 | $98,677 | $96,337 | $2,340 |
+| 0.95 | 1.96 | $99,808 | $95,222 | $4,586 |
+| 0.99 | 2.58 | $100,545 | $94,520 | $6,025 |
+
+**When to use which:**
+
+- **±1σ (default)** — typical expected move for the next candle. Good for scalping SL/TP targets and assessing whether a move is "normal" or significant
+- **95% VaR** — worst reasonable scenario. Good for risk management, position sizing, and stop-losses that shouldn't be triggered by noise
+- **99% VaR** — extreme tail risk. Good for stress testing and margin calculations
+
 **Parameters:**
 
 | Parameter | Type | Default | Description |
@@ -48,6 +79,7 @@ const result = predict(candles, '4h', vwap);
 | `candles` | `Candle[]` | required | OHLCV candle data |
 | `interval` | `CandleInterval` | required | Candle timeframe |
 | `currentPrice` | `number` | last close | Reference price to center the corridor |
+| `confidence` | `number` | `0.6827` | Two-sided probability in (0,1). Controls band width via `z = probit(confidence)` |
 
 **Returns:** `PredictionResult`
 
@@ -55,9 +87,9 @@ const result = predict(candles, '4h', vwap);
 interface PredictionResult {
   currentPrice: number;           // Reference price
   sigma: number;                  // One-period volatility (decimal, e.g. 0.012 = 1.2%)
-  move: number;                   // +/- price move = currentPrice * sigma
-  upperPrice: number;             // currentPrice + move
-  lowerPrice: number;             // currentPrice - move
+  move: number;                   // Upward price move = upperPrice - currentPrice
+  upperPrice: number;             // P · exp(+z·σ)
+  lowerPrice: number;             // P · exp(-z·σ)
   modelType: 'garch' | 'egarch' | 'gjr-garch' | 'har-rv' | 'novas'; // Auto-selected model
   reliable: boolean;              // Quality flag (convergence + persistence + Ljung-Box)
 }
@@ -65,9 +97,9 @@ interface PredictionResult {
 
 ---
 
-### `predictRange(candles, interval, steps, currentPrice?)`
+### `predictRange(candles, interval, steps, currentPrice?, confidence?)`
 
-Forecast cumulative expected price range over multiple candles. Cumulative sigma = sqrt(sigma_1^2 + sigma_2^2 + ... + sigma_n^2). Use for swing trades where you hold across multiple periods.
+Forecast cumulative expected price range over multiple candles. Cumulative sigma = sqrt(sigma_1^2 + sigma_2^2 + ... + sigma_n^2). Uses the same log-normal bands as `predict`. Use for swing trades where you hold across multiple periods.
 
 ```typescript
 import { predictRange } from 'garch';
@@ -76,12 +108,15 @@ const range = predictRange(candles, '4h', 5);
 // {
 //   currentPrice: 97500,
 //   sigma: 0.027,           // cumulative ~2.7% over 5 candles
-//   move: 2632,             // +/-$2632 total range
-//   upperPrice: 100132,
-//   lowerPrice: 94868,
+//   move: 2669,             // upward expected move
+//   upperPrice: 100169,     // P·exp(+z·σ)
+//   lowerPrice: 94901,      // P·exp(-z·σ)
 //   modelType: 'egarch',
 //   reliable: true
 // }
+
+// 95% VaR over 5 candles
+const var95 = predictRange(candles, '4h', 5, undefined, 0.95);
 ```
 
 **Parameters:**
@@ -92,20 +127,25 @@ const range = predictRange(candles, '4h', 5);
 | `interval` | `CandleInterval` | required | Candle timeframe |
 | `steps` | `number` | required | Number of candles to forecast over |
 | `currentPrice` | `number` | last close | Reference price |
+| `confidence` | `number` | `0.6827` | Two-sided probability in (0,1) |
 
 **Returns:** `PredictionResult` (same structure as `predict`)
 
 ---
 
-### `backtest(candles, interval, requiredPercent?)`
+### `backtest(candles, interval, confidence?, requiredPercent?)`
 
-Walk-forward validation of `predict`. Uses 75% of candles for fitting, 25% for testing. Checks if the model's +-1 sigma corridor captures actual price moves at the required hit rate.
+Walk-forward validation of `predict`. Uses 75% of candles for fitting, 25% for testing. Checks if the model's price corridor captures actual price moves at the required hit rate.
+
+`confidence` and `requiredPercent` are independent: `confidence` controls the **band width** (via `probit`), `requiredPercent` controls the **pass/fail threshold**.
 
 ```typescript
 import { backtest } from 'garch';
 
-backtest(candles, '4h');     // true  -- hit rate >= 68% (default)
-backtest(candles, '4h', 50); // true  -- hit rate >= 50% (custom)
+backtest(candles, '4h');                   // ±1σ band, hit rate >= 68%
+backtest(candles, '4h', 0.95);            // 95% VaR band, hit rate >= 68%
+backtest(candles, '4h', 0.95, 90);        // 95% VaR band, hit rate >= 90%
+backtest(candles, '4h', undefined, 50);   // ±1σ band, hit rate >= 50%
 ```
 
 **Parameters:**
@@ -114,7 +154,8 @@ backtest(candles, '4h', 50); // true  -- hit rate >= 50% (custom)
 |-----------|------|---------|-------------|
 | `candles` | `Candle[]` | required | OHLCV candle data |
 | `interval` | `CandleInterval` | required | Candle timeframe |
-| `requiredPercent` | `number` | `68` | Minimum hit rate (+-1 sigma ~ 68% theoretically) |
+| `confidence` | `number` | `0.6827` | Two-sided probability in (0,1) for the prediction band |
+| `requiredPercent` | `number` | `68` | Minimum hit rate (0–100) to pass |
 
 **Returns:** `boolean`
 
@@ -402,6 +443,69 @@ sigma^2_GK = (1/n) * sum[ 0.5 * ln(H/L)^2 - (2*ln2 - 1) * ln(C/O)^2 ]
 
 ~5x more efficient than close-to-close variance.
 
+### Log-Normal Price Bands
+
+GARCH models volatility of **log-returns**, not absolute price changes. The correct mapping from log-return volatility back to price space uses the exponential:
+
+```
+upperPrice = P · exp(+z · sigma)
+lowerPrice = P · exp(-z · sigma)
+```
+
+where `z = probit(confidence)` is the z-score corresponding to the desired two-sided confidence level. This produces **asymmetric** bands (upside > downside in absolute terms) and guarantees `lowerPrice > 0`.
+
+The previous linear approximation `P · (1 ± sigma)` is a first-order Taylor expansion of `exp(±sigma)`. The difference grows with sigma:
+
+| sigma | Linear `1 + sigma` | Exact `exp(sigma)` | Error |
+|-------|--------------------|--------------------|-------|
+| 0.02 | 1.0200 | 1.0202 | ~0.01% |
+| 0.10 | 1.1000 | 1.1052 | ~0.5% |
+| 0.30 | 1.3000 | 1.3499 | ~3.8% |
+
+### Probit (Inverse Normal CDF)
+
+`probit(confidence)` computes the inverse of the standard normal CDF (Phi^{-1}). It converts a two-sided probability to a z-score:
+
+```
+confidence = P(-z < Z < z),  Z ~ N(0,1)
+z = probit(confidence)
+```
+
+There is no closed-form solution for Phi^{-1} — it is a transcendental equation. The implementation uses **Acklam's rational approximation** (Peter J. Acklam, 2002) with max relative error < 1.15 x 10^{-9}.
+
+**Step 1** — convert two-sided confidence to upper-tail probability:
+
+```
+p = (1 + confidence) / 2
+```
+
+**Step 2** — piecewise rational approximation over three regions:
+
+**Central region** (0.02425 <= p <= 0.97575) — covers ~95% of inputs:
+
+```
+q = p - 0.5
+r = q^2
+z = (a1·r^5 + a2·r^4 + a3·r^3 + a4·r^2 + a5·r + a6) · q
+    / (b1·r^5 + b2·r^4 + b3·r^3 + b4·r^2 + b5·r + 1)
+```
+
+**Tails** (p < 0.02425 or p > 0.97575):
+
+```
+q = sqrt(-2·ln(p))          // left tail
+z = (c1·q^5 + ... + c6) / (d1·q^4 + ... + 1)
+```
+
+For the right tail: `q = sqrt(-2·ln(1-p))`, result is negated. The 16 coefficients (a1–a6, b1–b5, c1–c6, d1–d4) are minimax-optimal rational approximation constants.
+
+| `confidence` | `p` | `z` | Meaning |
+|-------------|-----|-----|---------|
+| 0.6827 | 0.8413 | 1.000 | ±1 sigma (default) |
+| 0.90 | 0.9500 | 1.645 | Moderate VaR |
+| 0.95 | 0.9750 | 1.960 | 95% VaR |
+| 0.99 | 0.9950 | 2.576 | Conservative VaR |
+
 ### Student-t Log-Likelihood
 
 All five models use a **Student-t** distribution for log-likelihood computation. Financial return series exhibit fat tails (excess kurtosis), and the Student-t captures this with an additional **degrees of freedom (df)** parameter:
@@ -452,13 +556,13 @@ where RV_t is Parkinson per-candle realized variance and sigma_t^2 is the model'
 
 ## Tests
 
-**923 tests** across **22 test files**. All passing.
+**932 tests** across **22 test files**. All passing.
 
 | Category | Files | Tests | What's covered |
 |----------|-------|-------|----------------|
 | Mathematical formulas | `math.test.ts` | 45 | GARCH/EGARCH variance recursion, log-likelihood, forecast formulas, AIC/BIC, QLIKE, Yang-Zhang, Garman-Klass, Ljung-Box, chi-squared |
 | Math coverage | `math-coverage.test.ts` | 79 | Parkinson formula verification, rv↔returns alignment, H=L fallback, Parkinson-based forecast, candle validation, reliable flag cascade, backtest validity, numerical precision, cross-model consistency, Realized GARCH/EGARCH/GJR-GARCH Candle[] vs number[], perCandleParkinson shared function |
-| Full pipeline coverage | `plan-coverage.test.ts` | 73 | End-to-end: fit, forecast, predict, predictRange, backtest, model selection |
+| Full pipeline coverage | `plan-coverage.test.ts` | 82 | End-to-end: fit, forecast, predict, predictRange, backtest, model selection |
 | GARCH unit | `garch.test.ts` | 10 | Parameter estimation, variance series, forecast convergence, candle vs price input |
 | EGARCH unit | `egarch.test.ts` | 11 | Leverage detection, asymmetric volatility, model comparison |
 | GJR-GARCH unit | `gjr-garch.test.ts` | 86 | Variance recursion (r² and Parkinson), indicator function I(r<0), forecast formula (one-step + multi-step), constraint barriers, computed fields, AIC/BIC numParams=5, estimation properties (perturbation, determinism), numerical stability, degenerate params, Realized path (Candle[] vs number[], flat candles, bad OHLC), options forwarding, immutability, instance isolation, cross-model consistency, scale invariance, property-based fuzz, predict/predictRange/backtest integration |

package/build/index.cjs

@@ -454,6 +454,61 @@ function qlike(varianceSeries, rv) {
     }
     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
@@ -1594,9 +1649,7 @@ function assertMinCandles(candles, interval) {
         }
     }
     const recommended = RECOMMENDED_CANDLES[interval];
-    if (candles.length < recommended) {
-        console.warn(`[garch] ${interval}: ${candles.length} candles provided, recommend ≥${recommended} for reliable results. Check reliable: true in output.`);
-    }
+    if (candles.length < recommended) ;
 }
 function fitGarchFamily(candles, periodsPerYear, steps) {
     // Fit all three GARCH-family models and pick the best by AIC
@@ -1722,21 +1775,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),
     };
 }
@@ -1744,26 +1801,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.
@@ -1771,16 +1830,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++;
@@ -1814,6 +1879,7 @@ exports.nelderMeadMultiStart = nelderMeadMultiStart;
 exports.perCandleParkinson = perCandleParkinson;
 exports.predict = predict;
 exports.predictRange = predictRange;
+exports.probit = probit;
 exports.profileStudentTDf = profileStudentTDf;
 exports.qlike = qlike;
 exports.sampleVariance = sampleVariance;

package/build/index.mjs

@@ -452,6 +452,61 @@ function qlike(varianceSeries, rv) {
     }
     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
@@ -1592,9 +1647,7 @@ function assertMinCandles(candles, interval) {
         }
     }
     const recommended = RECOMMENDED_CANDLES[interval];
-    if (candles.length < recommended) {
-        console.warn(`[garch] ${interval}: ${candles.length} candles provided, recommend ≥${recommended} for reliable results. Check reliable: true in output.`);
-    }
+    if (candles.length < recommended) ;
 }
 function fitGarchFamily(candles, periodsPerYear, steps) {
     // Fit all three GARCH-family models and pick the best by AIC
@@ -1720,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),
     };
 }
@@ -1742,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.
@@ -1769,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++;
@@ -1788,4 +1853,4 @@ function backtest(candles, interval, requiredPercent = BACKTEST_REQUIRED_PERCENT
     return (hits / total) * 100 >= requiredPercent;
 }
 
-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 };
+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, probit, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "garch",
-  "version": "1.1.0",
-  "description": "GARCH and EGARCH volatility models for TypeScript",
-  "type": "module",
-  "main": "./build/index.cjs",
-  "module": "./build/index.mjs",
-  "types": "./types.d.ts",
-  "exports": {
-    ".": {
-      "types": "./types.d.ts",
-      "import": "./build/index.mjs",
-      "require": "./build/index.cjs"
-    }
-  },
-  "files": [
-    "build",
-    "types.d.ts",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "rollup -c",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "garch",
-    "egarch",
-    "volatility",
-    "finance",
-    "econometrics",
-    "time-series"
-  ],
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^20.10.0",
-    "@vitest/coverage-v8": "^1.6.1",
-    "rollup": "^4.57.1",
-    "rollup-plugin-dts": "^6.3.0",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "tslib": "^2.8.1",
-    "typescript": "^5.3.0",
-    "vitest": "^1.0.0"
-  }
-}
+{
+  "name": "garch",
+  "version": "1.2.1",
+  "description": "GARCH and EGARCH volatility models for TypeScript",
+  "type": "module",
+  "main": "./build/index.cjs",
+  "module": "./build/index.mjs",
+  "types": "./types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./build/index.mjs",
+      "require": "./build/index.cjs"
+    }
+  },
+  "files": [
+    "build",
+    "types.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "garch",
+    "egarch",
+    "volatility",
+    "finance",
+    "econometrics",
+    "time-series"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "rollup": "^4.57.1",
+    "rollup-plugin-dts": "^6.3.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "tslib": "^2.8.1",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/types.d.ts

@@ -487,6 +487,14 @@ declare function profileStudentTDf(returns: number[], varianceSeries: number[]):
  * of how the model was calibrated (MLE, OLS, D², etc.).
  */
 declare function qlike(varianceSeries: number[], rv: number[]): number;
+/**
+ * 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).
+ */
+declare function probit(confidence: number): number;
 
 type CandleInterval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '6h' | '8h';
 interface PredictionResult {
@@ -501,26 +509,31 @@ interface PredictionResult {
 /**
  * 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.
  */
-declare function predict(candles: Candle[], interval: CandleInterval, currentPrice?: number): PredictionResult;
+declare function predict(candles: Candle[], interval: CandleInterval, currentPrice?: number, confidence?: number): PredictionResult;
 /**
  * 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σ).
  */
-declare function predictRange(candles: Candle[], interval: CandleInterval, steps: number, currentPrice?: number): PredictionResult;
+declare function predictRange(candles: Candle[], interval: CandleInterval, steps: number, currentPrice?: number, confidence?: number): PredictionResult;
 /**
  * Walk-forward backtest of predict.
  *
  * 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.
  */
-declare function backtest(candles: Candle[], interval: CandleInterval, requiredPercent?: number): boolean;
+declare function backtest(candles: Candle[], interval: CandleInterval, confidence?: number, requiredPercent?: number): boolean;
 
 declare function nelderMead(fn: (x: number[]) => number, x0: number[], options?: {
     maxIter?: number;
@@ -536,5 +549,5 @@ declare function nelderMeadMultiStart(fn: (x: number[]) => number, x0: number[],
     restarts?: number;
 }): OptimizerResult;
 
-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 };
+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, probit, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTNegLL, yangZhangVariance };
 export type { CalibrationResult, Candle, CandleInterval, EgarchOptions, EgarchParams, GarchOptions, GarchParams, GjrGarchOptions, GjrGarchParams, HarRvOptions, HarRvParams, LeverageStats, NoVaSOptions, NoVaSParams, OptimizerResult, PredictionResult, VolatilityForecast };