garch 1.0.2 → 1.0.3

package/README.md

@@ -13,193 +13,247 @@
 npm install garch
 ```
 
-## Usage
+## API
 
-### GARCH(1,1)
+### `predict(candles, interval, currentPrice?)`
+
+Forecast expected price range for the next candle (t+1). Auto-selects GARCH or EGARCH based on leverage effect. Returns a +-1 sigma price corridor.
 
 ```typescript
-import { calibrateGarch, Garch } from 'garch';
+import { predict } from 'garch';
+import type { Candle } from 'garch';
 
-// From price array
-const prices = [100, 101, 99, 102, 98, ...];
-const result = calibrateGarch(prices, { periodsPerYear: 252 });
+const candles: Candle[] = await fetchCandles('BTCUSDT', '4h', 200);
 
-console.log(result.params);
+const result = predict(candles, '4h');
 // {
-//   omega: 0.000012,
-//   alpha: 0.08,
-//   beta: 0.89,
-//   persistence: 0.97,
-//   unconditionalVariance: 0.0004,
-//   annualizedVol: 31.7
+//   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
+//   modelType: 'egarch',
+//   reliable: true
 // }
 
-// Or use the class for more control
-const model = new Garch(prices, { periodsPerYear: 252 });
-const fit = model.fit();
-
-// Get variance series
-const variance = model.getVarianceSeries(fit.params);
-
-// Forecast 10 periods ahead
-const forecast = model.forecast(fit.params, 10);
-console.log(forecast.annualized); // [32.1, 31.9, 31.8, ...]
+// Pass VWAP or any reference price as 3rd argument
+const result = predict(candles, '4h', vwap);
 ```
 
-### EGARCH(1,1)
+**Parameters:**
 
-EGARCH captures asymmetric volatility (leverage effect):
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `candles` | `Candle[]` | required | OHLCV candle data |
+| `interval` | `CandleInterval` | required | Candle timeframe |
+| `currentPrice` | `number` | last close | Reference price to center the corridor |
+
+**Returns:** `PredictionResult`
 
 ```typescript
-import { calibrateEgarch, Egarch, checkLeverageEffect } from 'garch';
+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
+  modelType: 'garch' | 'egarch'; // Auto-selected model
+  reliable: boolean;              // Quality flag (convergence + persistence + Ljung-Box)
+}
+```
+
+---
 
-// Check if EGARCH is warranted
-const returns = calculateReturnsFromPrices(prices);
-const leverage = checkLeverageEffect(returns);
-console.log(leverage);
-// { negativeVol: 0.021, positiveVol: 0.015, ratio: 1.4, recommendation: 'egarch' }
+### `predictRange(candles, interval, steps, currentPrice?)`
 
-// Fit EGARCH
-const result = calibrateEgarch(prices, { periodsPerYear: 365 }); // crypto = 365
+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.
 
-console.log(result.params);
+```typescript
+import { predictRange } from 'garch';
+
+const range = predictRange(candles, '4h', 5);
 // {
-//   omega: -0.12,
-//   alpha: 0.15,
-//   gamma: -0.08,  // negative = leverage effect
-//   beta: 0.95,
-//   persistence: 0.95,
-//   annualizedVol: 45.2,
-//   leverageEffect: -0.08
+//   currentPrice: 97500,
+//   sigma: 0.027,           // cumulative ~2.7% over 5 candles
+//   move: 2632,             // +/-$2632 total range
+//   upperPrice: 100132,
+//   lowerPrice: 94868,
+//   modelType: 'egarch',
+//   reliable: true
 // }
 ```
 
-### From OHLCV Candles
+**Parameters:**
 
-```typescript
-import { Candle, calibrateGarch } from 'garch';
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `candles` | `Candle[]` | required | OHLCV candle data |
+| `interval` | `CandleInterval` | required | Candle timeframe |
+| `steps` | `number` | required | Number of candles to forecast over |
+| `currentPrice` | `number` | last close | Reference price |
 
-const candles: Candle[] = [
-  { open: 100, high: 102, low: 99, close: 101, volume: 1000 },
-  { open: 101, high: 103, low: 100, close: 99, volume: 1200 },
-  // ...
-];
+**Returns:** `PredictionResult` (same structure as `predict`)
 
-const result = calibrateGarch(candles);
-```
+---
 
-### Model Selection
+### `backtest(candles, interval, requiredPercent?)`
 
-```typescript
-import { calibrateGarch, calibrateEgarch } from 'garch';
+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.
 
-const garch = calibrateGarch(prices);
-const egarch = calibrateEgarch(prices);
+```typescript
+import { backtest } from 'garch';
 
-// Compare using AIC (lower is better)
-if (egarch.diagnostics.aic < garch.diagnostics.aic) {
-  console.log('EGARCH fits better');
-}
+backtest(candles, '4h');     // true  -- hit rate >= 68% (default)
+backtest(candles, '4h', 50); // true  -- hit rate >= 50% (custom)
 ```
 
-## API
+**Parameters:**
 
-### `calibrateGarch(data, options?)`
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `candles` | `Candle[]` | required | OHLCV candle data |
+| `interval` | `CandleInterval` | required | Candle timeframe |
+| `requiredPercent` | `number` | `68` | Minimum hit rate (+-1 sigma ~ 68% theoretically) |
 
-Calibrate GARCH(1,1) model.
+**Returns:** `boolean`
 
-**Parameters:**
-- `data`: `Candle[]` or `number[]` (prices)
-- `options.periodsPerYear`: Annualization factor (default: 252)
-- `options.maxIter`: Maximum optimizer iterations (default: 1000)
-- `options.tol`: Convergence tolerance (default: 1e-8)
+---
 
-**Returns:** `CalibrationResult<GarchParams>`
+## Supported Intervals
 
-### `calibrateEgarch(data, options?)`
+| Interval | Min Candles | Periods/Year | Coverage |
+|----------|-------------|--------------|----------|
+| `1m` | 500 | 525,600 | ~8-16 hours |
+| `3m` | 500 | 175,200 | ~25 hours |
+| `5m` | 500 | 105,120 | ~1.7 days |
+| `15m` | 300 | 35,040 | ~3 days |
+| `30m` | 200 | 17,520 | ~4 days |
+| `1h` | 200 | 8,760 | ~8 days |
+| `2h` | 200 | 4,380 | ~17 days |
+| `4h` | 200 | 2,190 | ~33 days |
+| `6h` | 150 | 1,460 | ~37 days |
+| `8h` | 150 | 1,095 | ~50 days |
 
-Calibrate EGARCH(1,1) model.
+## Timeframes
 
-**Parameters:** Same as `calibrateGarch`
+The `periodsPerYear` value controls annualization of volatility. When using `predict`/`predictRange`/`backtest`, this is handled automatically via the `interval` parameter. When using `Garch`/`Egarch` classes directly, pass `periodsPerYear` manually.
 
-**Returns:** `CalibrationResult<EgarchParams>`
+| Timeframe | `periodsPerYear` | Notes |
+|-----------|-----------------|-------|
+| **1m** | `525,600` | 1440/day x 365 |
+| **3m** | `175,200` | 480/day x 365 |
+| **5m** | `105,120` | 288/day x 365 |
+| **15m** | `35,040` | 96/day x 365 |
+| **30m** | `17,520` | 48/day x 365 |
+| **1h** | `8,760` | 24/day x 365 |
+| **2h** | `4,380` | 12/day x 365 |
+| **4h** | `2,190` | 6/day x 365 |
+| **6h** | `1,460` | 4/day x 365 |
+| **8h** | `1,095` | 3/day x 365 |
 
-### `checkLeverageEffect(returns)`
+Lower timeframes contain more microstructure noise — use larger datasets to compensate.
 
-Check for asymmetric volatility.
+## Math
 
-**Returns:** `{ negativeVol, positiveVol, ratio, recommendation }`
+### GARCH(1,1)
 
-### Classes
+Conditional variance model (Bollerslev, 1986):
 
-`Garch` and `Egarch` classes provide:
-- `.fit(options?)` - Calibrate parameters
-- `.getVarianceSeries(params)` - Compute conditional variance
-- `.forecast(params, steps)` - Multi-step variance forecast
-- `.getReturns()` - Get computed returns
+```
+sigma_t^2 = omega + alpha * epsilon_{t-1}^2 + beta * sigma_{t-1}^2
+```
 
-## Timeframes
+- **omega** > 0 — long-run variance anchor
+- **alpha** >= 0 — shock reaction (how much yesterday's surprise matters)
+- **beta** >= 0 — persistence (memory of past variance)
+- Stationarity constraint: **alpha + beta < 1**
+- Unconditional variance: **E[sigma^2] = omega / (1 - alpha - beta)**
 
-The library works with any candle timeframe. The only thing that changes is the `periodsPerYear` option, which controls annualization of volatility.
+Parameter estimation via **Gaussian MLE** (maximum likelihood):
 
-| Timeframe | `periodsPerYear` | Notes |
-|-----------|-----------------|-------|
-| **1d** | `252` (default) | Trading days per year |
-| **4h** | `1512` | 252 × 6 |
-| **1h** | `6048` (crypto) / `1638` (stocks) | Crypto trades 24/7, stocks ~6.5h/day |
-| **15m** | `24192` (crypto) / `6552` (stocks) | 96 or 26 bars per day × 252 |
-| **1m** | `362880` (crypto) / `393120` (stocks) | 1440 or 390 bars per day × 252 |
+```
+LL = -0.5 * sum[ ln(sigma_t^2) + epsilon_t^2 / sigma_t^2 ]
+```
 
-```typescript
-// Daily candles (default)
-calibrateGarch(prices);
+Multi-step forecast converges to unconditional variance:
 
-// 4-hour candles
-calibrateGarch(prices, { periodsPerYear: 1512 });
+```
+sigma_{t+h}^2 = omega + (alpha + beta) * sigma_{t+h-1}^2
+```
+
+### EGARCH(1,1)
+
+Exponential GARCH (Nelson, 1991). Models log-variance, capturing asymmetric volatility:
 
-// 15-minute candles (crypto, 24/7 market)
-calibrateGarch(prices, { periodsPerYear: 24192 });
+```
+ln(sigma_t^2) = omega + alpha * (|z_{t-1}| - sqrt(2/pi)) + gamma * z_{t-1} + beta * ln(sigma_{t-1}^2)
 ```
 
-**Minimum data:** 50 candles are required for stable parameter estimation.
+Where **z_t = epsilon_t / sigma_t** is the standardized residual, **sqrt(2/pi) ~ 0.7979**.
 
-**Recommended timeframes:** 1d and 4h are the most reliable for GARCH models. Lower timeframes (15m, 1m) contain more microstructure noise which can degrade calibration quality — use larger datasets to compensate.
+- **gamma** < 0 — leverage effect (negative returns increase vol more than positive)
+- No positivity constraints needed (log-variance is always real)
+- Stationarity: **|beta| < 1**
+- Unconditional variance: **E[sigma^2] ~ exp(omega / (1 - beta))**
 
-## Model Details
+### Model Auto-Selection
 
-### GARCH(1,1)
+`predict` and `predictRange` automatically choose between GARCH and EGARCH:
+
+1. Compute volatility of negative returns vs. positive returns
+2. If ratio > 1.2 — use EGARCH (significant leverage effect detected)
+3. Otherwise — use simpler GARCH
+
+### Variance Estimators
+
+**Yang-Zhang** (used as initial variance for model fitting):
 
 ```
-σ²ₜ = ω + α·ε²ₜ₋₁ + β·σ²ₜ₋₁
+sigma^2_YZ = sigma^2_overnight + k * sigma^2_close + (1-k) * sigma^2_RS
 ```
 
-- `ω` (omega) > 0: constant term
-- `α` (alpha) ≥ 0: reaction to shocks
-- `β` (beta) ≥ 0: persistence
-- Stationarity: α + β < 1
+Combines overnight gaps, open-to-close moves, and Rogers-Satchell intraday range. More robust than close-to-close for OHLC data.
 
-### EGARCH(1,1)
+**Garman-Klass** (fallback):
 
 ```
-ln(σ²ₜ) = ω + α·(|zₜ₋₁| - E[|z|]) + γ·zₜ₋₁ + β·ln(σ²ₜ₋₁)
+sigma^2_GK = (1/n) * sum[ 0.5 * ln(H/L)^2 - (2*ln2 - 1) * ln(C/O)^2 ]
 ```
 
-- `γ` (gamma) < 0: leverage effect (negative returns increase vol more)
-- No positivity constraints needed (models log-variance)
-- `|β|` < 1 for stationarity
+~5x more efficient than close-to-close variance.
 
-### Model Selection
+### Reliability Check
 
-```typescript
-import { calibrateGarch, calibrateEgarch } from 'garch';
+The `reliable` flag in `PredictionResult` is `true` when all three conditions hold:
 
-const garch = calibrateGarch(prices);
-const egarch = calibrateEgarch(prices);
+1. Optimizer converged
+2. Persistence < 0.999 (not near unit root)
+3. Ljung-Box test on squared standardized residuals: p-value >= 0.05 (no residual autocorrelation)
 
-// Compare using AIC (lower is better)
-if (egarch.diagnostics.aic < garch.diagnostics.aic) {
-  console.log('EGARCH fits better — leverage effect is significant');
-}
+### Optimization
+
+Parameters are estimated via **Nelder-Mead** simplex method (derivative-free). Default: 1000 iterations, tolerance 1e-8. Model comparison uses **AIC** (2k - 2LL) and **BIC** (k*ln(n) - 2LL).
+
+## Tests
+
+**400 tests** across **17 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, Yang-Zhang, Garman-Klass, Ljung-Box, chi-squared |
+| Full pipeline coverage | `plan-coverage.test.ts` | 73 | 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 via AIC |
+| Optimizer | `optimizer.test.ts`, `optimizer-shrink.test.ts` | 16 | Nelder-Mead on Rosenbrock/quadratic/parabolic, convergence, shrinking |
+| Statistical properties | `properties.test.ts` | 13 | Parameter recovery from synthetic data, local LL maximum, unconditional variance |
+| Regression | `regression.test.ts` | 9 | Parameter recovery, deterministic outputs |
+| Stability | `stability.test.ts` | 10 | Long-term forecast behavior, variance convergence |
+| Robustness | `robustness.test.ts` | 53 | Extreme moves, stress scenarios |
+| Edge cases | `edge-cases.test.ts`, `coverage-gaps*.test.ts` | 148 | Insufficient data, near-unit-root, zero returns, constant prices, negative prices, overflow/underflow, trending data, 10K+ data points |
+| Miscellaneous | `misc.test.ts` | 12 | Integration scenarios, different intervals |
+
+```bash
+npm test        # run all tests
 ```
 
 ## License

package/build/index.cjs

@@ -112,7 +112,7 @@ function shrink(simplex, values, sigma, fn, n) {
 function calculateReturns(candles) {
     const returns = [];
     for (let i = 1; i < candles.length; i++) {
-        if (candles[i].close <= 0 || candles[i - 1].close <= 0) {
+        if (!(candles[i].close > 0) || !(candles[i - 1].close > 0)) {
             throw new Error(`Invalid close price at index ${i}`);
         }
         returns.push(Math.log(candles[i].close / candles[i - 1].close));
@@ -125,7 +125,7 @@ function calculateReturns(candles) {
 function calculateReturnsFromPrices(prices) {
     const returns = [];
     for (let i = 1; i < prices.length; i++) {
-        if (prices[i] <= 0 || prices[i - 1] <= 0) {
+        if (!(prices[i] > 0 && Number.isFinite(prices[i])) || !(prices[i - 1] > 0 && Number.isFinite(prices[i - 1]))) {
             throw new Error(`Invalid price at index ${i}`);
         }
         returns.push(Math.log(prices[i] / prices[i - 1]));
@@ -169,11 +169,115 @@ function checkLeverageEffect(returns) {
         recommendation: ratio > 1.2 ? 'egarch' : 'garch',
     };
 }
+/**
+ * Garman-Klass (1980) variance estimator using OHLC data.
+ *
+ * σ²_GK = (1/n) Σ [ 0.5·(ln(H/L))² − (2ln2−1)·(ln(C/O))² ]
+ *
+ * ~5x more efficient than close-to-close variance.
+ */
+function garmanKlassVariance(candles) {
+    const n = candles.length;
+    const coeff = 2 * Math.LN2 - 1;
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+        const { open, high, low, close } = candles[i];
+        const hl = Math.log(high / low);
+        const co = Math.log(close / open);
+        sum += 0.5 * hl * hl - coeff * co * co;
+    }
+    return sum / n;
+}
+/**
+ * Yang-Zhang (2000) variance estimator using OHLC data.
+ *
+ * Combines overnight (open vs prev close), open-to-close,
+ * and Rogers-Satchell components. More efficient than Garman-Klass
+ * and handles overnight gaps (relevant for stocks).
+ *
+ * σ²_YZ = σ²_overnight + k·σ²_close + (1−k)·σ²_RS
+ */
+function yangZhangVariance(candles) {
+    const n = candles.length;
+    if (n < 2)
+        return garmanKlassVariance(candles);
+    const k = 0.34 / (1.34 + (n + 1) / (n - 1));
+    let overnightSum = 0;
+    let closeSum = 0;
+    let rsSum = 0;
+    let count = 0;
+    for (let i = 1; i < n; i++) {
+        const prevClose = candles[i - 1].close;
+        const { open, high, low, close } = candles[i];
+        const overnight = Math.log(open / prevClose);
+        const co = Math.log(close / open);
+        const hc = Math.log(high / close);
+        const ho = Math.log(high / open);
+        const lc = Math.log(low / close);
+        const lo = Math.log(low / open);
+        overnightSum += overnight * overnight;
+        closeSum += co * co;
+        rsSum += ho * hc + lo * lc;
+        count++;
+    }
+    const overnightVar = overnightSum / count;
+    const closeVar = closeSum / count;
+    const rsVar = rsSum / count;
+    return overnightVar + k * closeVar + (1 - k) * rsVar;
+}
 /**
  * Expected value of |Z| where Z ~ N(0,1)
  * E[|Z|] = sqrt(2/π)
  */
 const EXPECTED_ABS_NORMAL = Math.sqrt(2 / Math.PI);
+/**
+ * Chi-squared survival function approximation (Wilson-Hilferty).
+ * P(X > x) where X ~ χ²(df)
+ */
+function chi2Survival(x, df) {
+    if (df <= 0 || x < 0)
+        return 1;
+    // Wilson-Hilferty normal approximation
+    const z = Math.cbrt(x / df) - (1 - 2 / (9 * df));
+    const denom = Math.sqrt(2 / (9 * df));
+    const normZ = z / denom;
+    // Standard normal CDF via error function approximation
+    return 1 - normalCDF(normZ);
+}
+function normalCDF(x) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(x));
+    const d = 0.3989422804014327; // 1/sqrt(2π)
+    const p = d * Math.exp(-0.5 * x * x) *
+        (t * (0.319381530 + t * (-0.356563782 + t * (1.781477937 + t * (-1.821255978 + t * 1.330274429)))));
+    return x >= 0 ? 1 - p : p;
+}
+/**
+ * Ljung-Box test for autocorrelation.
+ *
+ * Q = n(n+2) Σ(k=1..m) ρ²_k / (n−k)
+ *
+ * Under H₀ (no autocorrelation), Q ~ χ²(m).
+ * Use on squared standardized residuals to test GARCH adequacy.
+ */
+function ljungBox(data, maxLag) {
+    const n = data.length;
+    const mean = data.reduce((s, v) => s + v, 0) / n;
+    const gamma0 = data.reduce((s, v) => s + (v - mean) ** 2, 0) / n;
+    if (gamma0 === 0)
+        return { statistic: 0, pValue: 1 };
+    let Q = 0;
+    for (let k = 1; k <= maxLag; k++) {
+        let gammaK = 0;
+        for (let t = k; t < n; t++) {
+            gammaK += (data[t] - mean) * (data[t - k] - mean);
+        }
+        gammaK /= n;
+        const rhoK = gammaK / gamma0;
+        Q += (rhoK * rhoK) / (n - k);
+    }
+    Q *= n * (n + 2);
+    return { statistic: Q, pValue: chi2Survival(Q, maxLag) };
+}
 /**
  * Calculate AIC (Akaike Information Criterion)
  */
@@ -210,11 +314,13 @@ class Garch {
         // Determine if input is candles or prices
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
+            this.initialVariance = sampleVariance(this.returns);
         }
         else {
-            this.returns = calculateReturns(data);
+            const candles = data;
+            this.returns = calculateReturns(candles);
+            this.initialVariance = yangZhangVariance(candles);
         }
-        this.initialVariance = sampleVariance(this.returns);
     }
     /**
      * Calibrate GARCH(1,1) parameters using Maximum Likelihood Estimation
@@ -256,7 +362,7 @@ class Garch {
         const persistence = alpha + beta;
         const unconditionalVariance = omega / (1 - persistence);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        const logLikelihood = -result.fx * 2;
+        const logLikelihood = -result.fx;
         const numParams = 3;
         return {
             params: {
@@ -362,11 +468,13 @@ class Egarch {
         }
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
+            this.initialVariance = sampleVariance(this.returns);
         }
         else {
-            this.returns = calculateReturns(data);
+            const candles = data;
+            this.returns = calculateReturns(candles);
+            this.initialVariance = yangZhangVariance(candles);
         }
-        this.initialVariance = sampleVariance(this.returns);
     }
     /**
      * Calibrate EGARCH(1,1) parameters using Maximum Likelihood Estimation
@@ -415,7 +523,7 @@ class Egarch {
         const unconditionalLogVar = omega / (1 - beta);
         const unconditionalVariance = Math.exp(unconditionalLogVar);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        const logLikelihood = -result.fx * 2;
+        const logLikelihood = -result.fx;
         const numParams = 4;
         return {
             params: {
@@ -515,14 +623,159 @@ function calibrateEgarch(data, options = {}) {
     return model.fit(options);
 }
 
+const MIN_CANDLES = {
+    '1m': 500,
+    '3m': 500,
+    '5m': 500,
+    '15m': 300,
+    '30m': 200,
+    '1h': 200,
+    '2h': 200,
+    '4h': 200,
+    '6h': 150,
+    '8h': 150,
+};
+const INTERVALS_PER_YEAR = {
+    '1m': 525_600,
+    '3m': 175_200,
+    '5m': 105_120,
+    '15m': 35_040,
+    '30m': 17_520,
+    '1h': 8_760,
+    '2h': 4_380,
+    '4h': 2_190,
+    '6h': 1_460,
+    '8h': 1_095,
+};
+function assertMinCandles(candles, interval) {
+    const min = MIN_CANDLES[interval];
+    if (candles.length < min) {
+        throw new Error(`Need at least ${min} candles for ${interval} interval, got ${candles.length}`);
+    }
+}
+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 });
+        const fit = model.fit();
+        return {
+            forecast: model.forecast(fit.params, steps),
+            modelType: 'egarch',
+            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(),
+    };
+}
+function checkReliable(fit) {
+    if (!fit.converged || fit.persistence >= 0.999)
+        return false;
+    // Ljung-Box on squared standardized residuals
+    const { returns, varianceSeries } = fit;
+    const squared = returns.map((r, i) => {
+        const z = r / Math.sqrt(varianceSeries[i]);
+        return z * z;
+    });
+    const lb = ljungBox(squared, 10);
+    return lb.pValue >= 0.05;
+}
+/**
+ * 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.
+ */
+function predict(candles, interval, currentPrice = candles[candles.length - 1].close) {
+    assertMinCandles(candles, interval);
+    const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], 1);
+    const sigma = fit.forecast.volatility[0];
+    const move = currentPrice * sigma;
+    return {
+        modelType: fit.modelType,
+        currentPrice,
+        sigma,
+        move,
+        upperPrice: currentPrice + move,
+        lowerPrice: currentPrice - move,
+        reliable: checkReliable(fit),
+    };
+}
+/**
+ * Forecast expected price range over multiple candles.
+ *
+ * Cumulative σ = √(σ₁² + σ₂² + ... + σₙ²) — total expected move over N periods.
+ * Use for swing trades where you hold across multiple candles.
+ */
+function predictRange(candles, interval, steps, currentPrice = candles[candles.length - 1].close) {
+    assertMinCandles(candles, interval);
+    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;
+    return {
+        modelType: fit.modelType,
+        currentPrice,
+        sigma,
+        move,
+        upperPrice: currentPrice + move,
+        lowerPrice: currentPrice - move,
+        reliable: checkReliable(fit),
+    };
+}
+// ── Backtest ──────────────────────────────────────────────────
+const BACKTEST_REQUIRED_PERCENT = 68;
+const BACKTEST_WINDOW_RATIO = 0.75;
+/**
+ * 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).
+ */
+function backtest(candles, interval, requiredPercent = BACKTEST_REQUIRED_PERCENT) {
+    assertMinCandles(candles, interval);
+    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 actual = candles[i + 1].close;
+        if (actual >= predicted.lowerPrice && actual <= predicted.upperPrice) {
+            hits++;
+        }
+        total++;
+    }
+    return (hits / total) * 100 >= requiredPercent;
+}
+
 exports.EXPECTED_ABS_NORMAL = EXPECTED_ABS_NORMAL;
 exports.Egarch = Egarch;
 exports.Garch = Garch;
+exports.backtest = backtest;
 exports.calculateReturns = calculateReturns;
 exports.calculateReturnsFromPrices = calculateReturnsFromPrices;
 exports.calibrateEgarch = calibrateEgarch;
 exports.calibrateGarch = calibrateGarch;
 exports.checkLeverageEffect = checkLeverageEffect;
+exports.garmanKlassVariance = garmanKlassVariance;
+exports.ljungBox = ljungBox;
 exports.nelderMead = nelderMead;
+exports.predict = predict;
+exports.predictRange = predictRange;
 exports.sampleVariance = sampleVariance;
 exports.sampleVarianceWithMean = sampleVarianceWithMean;
+exports.yangZhangVariance = yangZhangVariance;

package/build/index.mjs

@@ -110,7 +110,7 @@ function shrink(simplex, values, sigma, fn, n) {
 function calculateReturns(candles) {
     const returns = [];
     for (let i = 1; i < candles.length; i++) {
-        if (candles[i].close <= 0 || candles[i - 1].close <= 0) {
+        if (!(candles[i].close > 0) || !(candles[i - 1].close > 0)) {
             throw new Error(`Invalid close price at index ${i}`);
         }
         returns.push(Math.log(candles[i].close / candles[i - 1].close));
@@ -123,7 +123,7 @@ function calculateReturns(candles) {
 function calculateReturnsFromPrices(prices) {
     const returns = [];
     for (let i = 1; i < prices.length; i++) {
-        if (prices[i] <= 0 || prices[i - 1] <= 0) {
+        if (!(prices[i] > 0 && Number.isFinite(prices[i])) || !(prices[i - 1] > 0 && Number.isFinite(prices[i - 1]))) {
             throw new Error(`Invalid price at index ${i}`);
         }
         returns.push(Math.log(prices[i] / prices[i - 1]));
@@ -167,11 +167,115 @@ function checkLeverageEffect(returns) {
         recommendation: ratio > 1.2 ? 'egarch' : 'garch',
     };
 }
+/**
+ * Garman-Klass (1980) variance estimator using OHLC data.
+ *
+ * σ²_GK = (1/n) Σ [ 0.5·(ln(H/L))² − (2ln2−1)·(ln(C/O))² ]
+ *
+ * ~5x more efficient than close-to-close variance.
+ */
+function garmanKlassVariance(candles) {
+    const n = candles.length;
+    const coeff = 2 * Math.LN2 - 1;
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+        const { open, high, low, close } = candles[i];
+        const hl = Math.log(high / low);
+        const co = Math.log(close / open);
+        sum += 0.5 * hl * hl - coeff * co * co;
+    }
+    return sum / n;
+}
+/**
+ * Yang-Zhang (2000) variance estimator using OHLC data.
+ *
+ * Combines overnight (open vs prev close), open-to-close,
+ * and Rogers-Satchell components. More efficient than Garman-Klass
+ * and handles overnight gaps (relevant for stocks).
+ *
+ * σ²_YZ = σ²_overnight + k·σ²_close + (1−k)·σ²_RS
+ */
+function yangZhangVariance(candles) {
+    const n = candles.length;
+    if (n < 2)
+        return garmanKlassVariance(candles);
+    const k = 0.34 / (1.34 + (n + 1) / (n - 1));
+    let overnightSum = 0;
+    let closeSum = 0;
+    let rsSum = 0;
+    let count = 0;
+    for (let i = 1; i < n; i++) {
+        const prevClose = candles[i - 1].close;
+        const { open, high, low, close } = candles[i];
+        const overnight = Math.log(open / prevClose);
+        const co = Math.log(close / open);
+        const hc = Math.log(high / close);
+        const ho = Math.log(high / open);
+        const lc = Math.log(low / close);
+        const lo = Math.log(low / open);
+        overnightSum += overnight * overnight;
+        closeSum += co * co;
+        rsSum += ho * hc + lo * lc;
+        count++;
+    }
+    const overnightVar = overnightSum / count;
+    const closeVar = closeSum / count;
+    const rsVar = rsSum / count;
+    return overnightVar + k * closeVar + (1 - k) * rsVar;
+}
 /**
  * Expected value of |Z| where Z ~ N(0,1)
  * E[|Z|] = sqrt(2/π)
  */
 const EXPECTED_ABS_NORMAL = Math.sqrt(2 / Math.PI);
+/**
+ * Chi-squared survival function approximation (Wilson-Hilferty).
+ * P(X > x) where X ~ χ²(df)
+ */
+function chi2Survival(x, df) {
+    if (df <= 0 || x < 0)
+        return 1;
+    // Wilson-Hilferty normal approximation
+    const z = Math.cbrt(x / df) - (1 - 2 / (9 * df));
+    const denom = Math.sqrt(2 / (9 * df));
+    const normZ = z / denom;
+    // Standard normal CDF via error function approximation
+    return 1 - normalCDF(normZ);
+}
+function normalCDF(x) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(x));
+    const d = 0.3989422804014327; // 1/sqrt(2π)
+    const p = d * Math.exp(-0.5 * x * x) *
+        (t * (0.319381530 + t * (-0.356563782 + t * (1.781477937 + t * (-1.821255978 + t * 1.330274429)))));
+    return x >= 0 ? 1 - p : p;
+}
+/**
+ * Ljung-Box test for autocorrelation.
+ *
+ * Q = n(n+2) Σ(k=1..m) ρ²_k / (n−k)
+ *
+ * Under H₀ (no autocorrelation), Q ~ χ²(m).
+ * Use on squared standardized residuals to test GARCH adequacy.
+ */
+function ljungBox(data, maxLag) {
+    const n = data.length;
+    const mean = data.reduce((s, v) => s + v, 0) / n;
+    const gamma0 = data.reduce((s, v) => s + (v - mean) ** 2, 0) / n;
+    if (gamma0 === 0)
+        return { statistic: 0, pValue: 1 };
+    let Q = 0;
+    for (let k = 1; k <= maxLag; k++) {
+        let gammaK = 0;
+        for (let t = k; t < n; t++) {
+            gammaK += (data[t] - mean) * (data[t - k] - mean);
+        }
+        gammaK /= n;
+        const rhoK = gammaK / gamma0;
+        Q += (rhoK * rhoK) / (n - k);
+    }
+    Q *= n * (n + 2);
+    return { statistic: Q, pValue: chi2Survival(Q, maxLag) };
+}
 /**
  * Calculate AIC (Akaike Information Criterion)
  */
@@ -208,11 +312,13 @@ class Garch {
         // Determine if input is candles or prices
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
+            this.initialVariance = sampleVariance(this.returns);
         }
         else {
-            this.returns = calculateReturns(data);
+            const candles = data;
+            this.returns = calculateReturns(candles);
+            this.initialVariance = yangZhangVariance(candles);
         }
-        this.initialVariance = sampleVariance(this.returns);
     }
     /**
      * Calibrate GARCH(1,1) parameters using Maximum Likelihood Estimation
@@ -254,7 +360,7 @@ class Garch {
         const persistence = alpha + beta;
         const unconditionalVariance = omega / (1 - persistence);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        const logLikelihood = -result.fx * 2;
+        const logLikelihood = -result.fx;
         const numParams = 3;
         return {
             params: {
@@ -360,11 +466,13 @@ class Egarch {
         }
         if (typeof data[0] === 'number') {
             this.returns = calculateReturnsFromPrices(data);
+            this.initialVariance = sampleVariance(this.returns);
         }
         else {
-            this.returns = calculateReturns(data);
+            const candles = data;
+            this.returns = calculateReturns(candles);
+            this.initialVariance = yangZhangVariance(candles);
         }
-        this.initialVariance = sampleVariance(this.returns);
     }
     /**
      * Calibrate EGARCH(1,1) parameters using Maximum Likelihood Estimation
@@ -413,7 +521,7 @@ class Egarch {
         const unconditionalLogVar = omega / (1 - beta);
         const unconditionalVariance = Math.exp(unconditionalLogVar);
         const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
-        const logLikelihood = -result.fx * 2;
+        const logLikelihood = -result.fx;
         const numParams = 4;
         return {
             params: {
@@ -513,4 +621,143 @@ function calibrateEgarch(data, options = {}) {
     return model.fit(options);
 }
 
-export { EXPECTED_ABS_NORMAL, Egarch, Garch, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, checkLeverageEffect, nelderMead, sampleVariance, sampleVarianceWithMean };
+const MIN_CANDLES = {
+    '1m': 500,
+    '3m': 500,
+    '5m': 500,
+    '15m': 300,
+    '30m': 200,
+    '1h': 200,
+    '2h': 200,
+    '4h': 200,
+    '6h': 150,
+    '8h': 150,
+};
+const INTERVALS_PER_YEAR = {
+    '1m': 525_600,
+    '3m': 175_200,
+    '5m': 105_120,
+    '15m': 35_040,
+    '30m': 17_520,
+    '1h': 8_760,
+    '2h': 4_380,
+    '4h': 2_190,
+    '6h': 1_460,
+    '8h': 1_095,
+};
+function assertMinCandles(candles, interval) {
+    const min = MIN_CANDLES[interval];
+    if (candles.length < min) {
+        throw new Error(`Need at least ${min} candles for ${interval} interval, got ${candles.length}`);
+    }
+}
+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 });
+        const fit = model.fit();
+        return {
+            forecast: model.forecast(fit.params, steps),
+            modelType: 'egarch',
+            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(),
+    };
+}
+function checkReliable(fit) {
+    if (!fit.converged || fit.persistence >= 0.999)
+        return false;
+    // Ljung-Box on squared standardized residuals
+    const { returns, varianceSeries } = fit;
+    const squared = returns.map((r, i) => {
+        const z = r / Math.sqrt(varianceSeries[i]);
+        return z * z;
+    });
+    const lb = ljungBox(squared, 10);
+    return lb.pValue >= 0.05;
+}
+/**
+ * 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.
+ */
+function predict(candles, interval, currentPrice = candles[candles.length - 1].close) {
+    assertMinCandles(candles, interval);
+    const fit = fitModel(candles, INTERVALS_PER_YEAR[interval], 1);
+    const sigma = fit.forecast.volatility[0];
+    const move = currentPrice * sigma;
+    return {
+        modelType: fit.modelType,
+        currentPrice,
+        sigma,
+        move,
+        upperPrice: currentPrice + move,
+        lowerPrice: currentPrice - move,
+        reliable: checkReliable(fit),
+    };
+}
+/**
+ * Forecast expected price range over multiple candles.
+ *
+ * Cumulative σ = √(σ₁² + σ₂² + ... + σₙ²) — total expected move over N periods.
+ * Use for swing trades where you hold across multiple candles.
+ */
+function predictRange(candles, interval, steps, currentPrice = candles[candles.length - 1].close) {
+    assertMinCandles(candles, interval);
+    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;
+    return {
+        modelType: fit.modelType,
+        currentPrice,
+        sigma,
+        move,
+        upperPrice: currentPrice + move,
+        lowerPrice: currentPrice - move,
+        reliable: checkReliable(fit),
+    };
+}
+// ── Backtest ──────────────────────────────────────────────────
+const BACKTEST_REQUIRED_PERCENT = 68;
+const BACKTEST_WINDOW_RATIO = 0.75;
+/**
+ * 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).
+ */
+function backtest(candles, interval, requiredPercent = BACKTEST_REQUIRED_PERCENT) {
+    assertMinCandles(candles, interval);
+    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 actual = candles[i + 1].close;
+        if (actual >= predicted.lowerPrice && actual <= predicted.upperPrice) {
+            hits++;
+        }
+        total++;
+    }
+    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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "garch",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "GARCH and EGARCH volatility models for TypeScript",
   "type": "module",
   "main": "./build/index.cjs",
@@ -37,6 +37,7 @@
   "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",

package/types.d.ts

@@ -178,11 +178,75 @@ declare function sampleVarianceWithMean(returns: number[]): number;
  * Check for leverage effect (asymmetry in volatility)
  */
 declare function checkLeverageEffect(returns: number[]): LeverageStats;
+/**
+ * Garman-Klass (1980) variance estimator using OHLC data.
+ *
+ * σ²_GK = (1/n) Σ [ 0.5·(ln(H/L))² − (2ln2−1)·(ln(C/O))² ]
+ *
+ * ~5x more efficient than close-to-close variance.
+ */
+declare function garmanKlassVariance(candles: Candle[]): number;
+/**
+ * Yang-Zhang (2000) variance estimator using OHLC data.
+ *
+ * Combines overnight (open vs prev close), open-to-close,
+ * and Rogers-Satchell components. More efficient than Garman-Klass
+ * and handles overnight gaps (relevant for stocks).
+ *
+ * σ²_YZ = σ²_overnight + k·σ²_close + (1−k)·σ²_RS
+ */
+declare function yangZhangVariance(candles: Candle[]): number;
 /**
  * Expected value of |Z| where Z ~ N(0,1)
  * E[|Z|] = sqrt(2/π)
  */
 declare const EXPECTED_ABS_NORMAL: number;
+/**
+ * Ljung-Box test for autocorrelation.
+ *
+ * Q = n(n+2) Σ(k=1..m) ρ²_k / (n−k)
+ *
+ * Under H₀ (no autocorrelation), Q ~ χ²(m).
+ * Use on squared standardized residuals to test GARCH adequacy.
+ */
+declare function ljungBox(data: number[], maxLag: number): {
+    statistic: number;
+    pValue: number;
+};
+
+type CandleInterval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '6h' | '8h';
+interface PredictionResult {
+    currentPrice: number;
+    sigma: number;
+    move: number;
+    upperPrice: number;
+    lowerPrice: number;
+    modelType: 'garch' | 'egarch';
+    reliable: boolean;
+}
+/**
+ * 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.
+ */
+declare function predict(candles: Candle[], interval: CandleInterval, currentPrice?: 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.
+ */
+declare function predictRange(candles: Candle[], interval: CandleInterval, steps: number, currentPrice?: 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).
+ */
+declare function backtest(candles: Candle[], interval: CandleInterval, requiredPercent?: number): boolean;
 
 declare function nelderMead(fn: (x: number[]) => number, x0: number[], options?: {
     maxIter?: number;
@@ -193,5 +257,5 @@ declare function nelderMead(fn: (x: number[]) => number, x0: number[], options?:
     sigma?: number;
 }): OptimizerResult;
 
-export { EXPECTED_ABS_NORMAL, Egarch, Garch, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, checkLeverageEffect, nelderMead, sampleVariance, sampleVarianceWithMean };
-export type { CalibrationResult, Candle, EgarchOptions, EgarchParams, GarchOptions, GarchParams, LeverageStats, OptimizerResult, VolatilityForecast };
+export { EXPECTED_ABS_NORMAL, Egarch, Garch, backtest, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, checkLeverageEffect, garmanKlassVariance, ljungBox, nelderMead, predict, predictRange, sampleVariance, sampleVarianceWithMean, yangZhangVariance };
+export type { CalibrationResult, Candle, CandleInterval, EgarchOptions, EgarchParams, GarchOptions, GarchParams, LeverageStats, OptimizerResult, PredictionResult, VolatilityForecast };