garch 1.2.4 → 2.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Petr Tripolsky
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Petr Tripolsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -20,7 +20,9 @@ npm install garch
 
 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.
+Uses **log-normal price bands**: `P·exp(±z·σ)`. 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.
+
+The multiplier `z` is **calibrated on the data itself**, not taken from a Gaussian table: the model's variance series is rescaled so standardized residuals have unit variance, then `z` blends the empirical |z| quantile of those residuals with the fitted Student-t(df) quantile (the empirical part dominates where the sample supports the tail, the t part takes over in the far tail). The actual multiplier used is returned as `zScore`.
 
 ```typescript
 import { predict } from 'garch';
@@ -35,37 +37,33 @@ const result = predict(candles, '4h');
 //   sigma: 0.012,          // 1.2% per-period volatility
 //   move: 1177,            // upward expected move (upper - current), in dollars
 //   movePercent: 1.21,     // upward expected move, in percent (0–100)
-//   upperPrice: 98677,     // P·exp(+σ) — ceiling
-//   lowerPrice: 96337,     // P·exp(-σ) — floor
+//   upperPrice: 98677,     // P·exp(+z·σ) — ceiling
+//   lowerPrice: 96337,     // P·exp(-z·σ) — floor
 //   modelType: 'egarch',
+//   df: 6.3,               // fitted Student-t tail thickness
+//   zScore: 0.97,          // corridor multiplier actually used
 //   reliable: true
 // }
 
-// 95% VaR band (z ≈ 1.96)
+// 95% VaR band
 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 |
+**Confidence → z (Gaussian reference only — actual z is data-driven):**
 
-Any value in (0, 1) is valid — the table above lists common choices, but `probit` computes z for arbitrary confidence.
+| `confidence` | Gaussian z | Typical fat-tail z (df≈5) | Meaning |
+|-------------|-----------|---------------------------|---------|
+| 0.6827 (default) | 1.00 | ≈0.86 | ±1σ, ~68% of moves captured |
+| 0.90 | 1.645 | ≈1.56 | Moderate VaR |
+| 0.95 | 1.96 | ≈1.99 | 95% VaR (standard) |
+| 0.99 | 2.576 | ≈3.12 | Conservative VaR |
 
-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:
+Any value in (0, 1) is valid. With fat-tailed market data the Gaussian table is systematically wrong — too wide in the center, dangerously narrow in the tails — which is why the corridor uses the data-calibrated multiplier instead. Check `result.zScore` for the value actually applied.
 
-| `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 |
+Higher confidence = wider corridor. `sigma` stays the same (it's the model's volatility estimate), only the z-multiplier changes.
 
 **When to use which:**
 
@@ -80,7 +78,7 @@ Higher confidence = wider corridor. `sigma` stays the same (it's the model's vol
 | `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)` |
+| `confidence` | `number` | `0.6827` | Two-sided probability in (0,1). Controls band width via the data-calibrated `zScore` |
 
 **Returns:** `PredictionResult`
 
@@ -93,6 +91,8 @@ interface PredictionResult {
   upperPrice: number;             // P · exp(+z·σ)
   lowerPrice: number;             // P · exp(-z·σ)
   modelType: 'garch' | 'egarch' | 'gjr-garch' | 'har-rv' | 'novas'; // Auto-selected model
+  df: number;                     // Fitted Student-t degrees of freedom (tail thickness)
+  zScore: number;                 // Corridor multiplier actually used for the bands
   reliable: boolean;              // Quality flag (convergence + persistence + Ljung-Box)
 }
 ```
@@ -140,7 +140,7 @@ const var95 = predictRange(candles, '4h', 5, undefined, 0.95);
 
 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**.
+`confidence` and `requiredPercent` are independent: `confidence` controls the **band width** (via the data-calibrated `zScore`), `requiredPercent` controls the **pass/fail threshold**.
 
 ```typescript
 import { backtest } from 'garch';
@@ -164,6 +164,169 @@ backtest(candles, '4h', undefined, 50);   // ±1σ band, hit rate >= 50%
 
 ---
 
+### `backtestStats(candles, interval, confidence?)`
+
+Same walk-forward loop as `backtest`, but returns the raw calibration numbers instead of a pass/fail flag. A well-calibrated setup has `hitRate ≈ confidence · 100` — run this on your own market data before trusting the corridor.
+
+```typescript
+import { backtestStats } from 'garch';
+
+const stats = backtestStats(candles, '4h', 0.95);
+// {
+//   hits: 61, total: 66, hitRate: 92.4,
+//   verdict: 'well-calibrated',   // Kupiec test: is 92.4 vs 95 failure or noise?
+//   pValue: 0.38,
+//   message: 'Coverage 92.4% vs nominal 95.0% over 66 points is consistent with a calibrated corridor (Kupiec p=0.3800).'
+// }
+
+// Every test point refits all 5 models, so by default the test span is
+// subsampled to at most ~100 refits. Control it explicitly:
+backtestStats(candles, '4h', 0.95, { stride: 1 });  // every candle (slow)
+backtestStats(candles, '4h', 0.95, { stride: 10 }); // every 10th candle
+```
+
+**Returns:** `BacktestStats`
+
+```typescript
+interface BacktestStats {
+  hits: number;     // closes that landed inside the corridor
+  total: number;    // walk-forward predictions made
+  hitRate: number;  // hits/total · 100 — compare with confidence · 100
+  verdict: 'well-calibrated' | 'too-narrow' | 'too-wide' | 'inconclusive';
+  pValue: number;   // Kupiec POF test — probability the gap is noise
+  message: string;  // plain-language interpretation with the numbers filled in
+}
+```
+
+`verdict` answers the question a raw hit rate cannot: 63% observed against 68%
+nominal is *fine* on 100 points (noise) and *broken* on 2,000 points. `too-narrow`
+means real risk exceeds what the corridor shows; `too-wide` means decisions based
+on it are overly conservative.
+
+---
+
+### `checkData(candles, interval)`
+
+Pre-flight check for a new data source — run it once before wiring a feed into
+`predict`. Errors are conditions `predict` would throw on; warnings degrade
+quality but do not block.
+
+```typescript
+import { checkData } from 'garch';
+
+const report = checkData(candles, '1h');
+// {
+//   ok: false,
+//   issues: [
+//     { code: 'UNSORTED', severity: 'error',
+//       message: 'Candles are not sorted by timestamp (index 812) — sort ascending before calling. Check your data feed.' },
+//     { code: 'DATA_GAPS', severity: 'warning',
+//       message: '~17 missing bars (2.1%) detected from timestamps — the seasonal profile and lag structure may be distorted. Check your feed for outages.' },
+//   ],
+//   recommendedCandles: 500,
+// }
+```
+
+Detects: too few candles, broken OHLC (with the failing index), unsorted or
+duplicated timestamps, gaps, candle spacing that contradicts the `interval`
+argument, and feeds where too many candles have `high === low`.
+
+---
+
+### `createPredictor(interval)`
+
+Stateful predictor for rolling use (bots, backtest loops). Each call warm-starts
+every optimizer from the previous window's optimum — same math, roughly 3× faster
+than calling `predict` in a loop. State is per-instrument: one predictor per symbol.
+
+```typescript
+import { createPredictor } from 'garch';
+
+const predictor = createPredictor('1h');
+setInterval(async () => {
+  const candles = await fetchCandles('BTCUSDT', '1h', 500);
+  const res = predictor.predict(candles, { confidence: 0.9 });
+  // ...
+}, 60 * 60 * 1000);
+```
+
+---
+
+## Warnings & errors
+
+`predict` explains itself instead of failing silently. Every result carries
+`warnings` (plain-language, with a `critical` flag — `reliable` is simply
+"no critical warning fired"), `modelWeights` (which model families are driving
+the forecast) and `seasonalityDetected`:
+
+```typescript
+const res = predict(candles, '1h', { confidence: 0.9 });
+if (!res.reliable) {
+  for (const w of res.warnings) console.log(`[${w.code}] ${w.message}`);
+  // [RESIDUAL_AUTOCORRELATION] Squared residuals stay autocorrelated (Ljung-Box p=0.012) —
+  // the model did not fully capture volatility clustering; the corridor may understate risk.
+}
+console.log(res.modelWeights); // { garch: 0.58, 'har-rv': 0.42 }
+```
+
+Errors are typed — catch by class, not by parsing messages:
+
+```typescript
+import { NotEnoughDataError, BadDataError, InvalidArgumentError } from 'garch';
+
+try {
+  const res = predict(candles, '1h');
+} catch (e) {
+  if (e instanceof NotEnoughDataError) await fetchMoreHistory();
+  else if (e instanceof BadDataError) alertDataPipeline(e.message); // broken OHLC, unsorted/duplicate timestamps
+  else if (e instanceof InvalidArgumentError) throw e;              // bug at the call site
+  else throw e;
+}
+```
+
+## Recipes
+
+**Stop-loss / take-profit from the corridor.** `lowerPrice` at confidence 0.90 is
+the level price stays above with ~95% probability (each tail carries 5%):
+
+```typescript
+const res = predictor.predict(candles, { confidence: 0.9 });
+if (res.reliable) {
+  placeOrder({ side: 'buy', stopLoss: res.lowerPrice, takeProfit: res.upperPrice });
+}
+```
+
+**Position sizing by volatility.** Risk a fixed dollar amount per corridor width
+instead of a fixed position size:
+
+```typescript
+const riskPerTrade = 100; // dollars you accept losing if price hits the lower band
+const size = riskPerTrade / (res.currentPrice - res.lowerPrice);
+```
+
+**Volatility filter.** Skip entries when the model cannot be trusted or the
+expected move is too small to cover fees:
+
+```typescript
+const feePct = 0.1; // round-trip, percent
+if (!res.reliable || res.movePercent < feePct * 2) return; // stand aside
+```
+
+**Calibration monitoring.** Once a day, verify the corridor still tells the truth
+on your instrument — and read the verdict, not the raw rate:
+
+```typescript
+const stats = backtestStats(candles, '1h', 0.9);
+if (stats.verdict === 'too-narrow') notify(stats.message); // real risk > shown risk
+```
+
+**Multi-candle horizon.** Corridor for "where will price be 12 hours from now"
+on 1h candles:
+
+```typescript
+const res = predictor.predictRange(candles, 12, { confidence: 0.95 });
+```
+
 ## Supported Intervals
 
 | Interval | Min Candles | Recommended | Periods/Year | Coverage |
@@ -179,12 +342,14 @@ backtest(candles, '4h', undefined, 50);   // ±1σ band, hit rate >= 50%
 | `6h` | 150 | 300 | 1,460 | ~37 days |
 | `8h` | 150 | 300 | 1,095 | ~50 days |
 
-For intervals below 1h, per-candle Parkinson RV is noisier — more data helps OLS and QLIKE model selection. A `console.warn` is emitted when candle count is below the recommended value. Always check `reliable: true` in the output.
+For intervals below 1h, per-candle Parkinson RV is noisier — more data helps OLS and QLIKE model selection. When the candle count is below the recommended value the result carries a non-critical `LOW_SAMPLE` warning. Always check `reliable: true` (and read `warnings`) in the output.
 
 ## Timeframes
 
 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.
 
+> **Scale caveat for direct class usage:** with `Candle[]` input the model recursions are driven by range-based Parkinson RV, so `params.unconditionalVariance` / `params.annualizedVol` are on the *realized-variance* scale, which can differ from the close-to-close return variance when ranges and returns disagree (gaps, thin wicks). `predict`/`predictRange` correct this automatically (standardized residuals are rescaled to unit variance before the corridor is built); raw `calibrate*` output is not corrected.
+
 | Timeframe | `periodsPerYear` | Notes |
 |-----------|-----------------|-------|
 | **1m** | `525,600` | 1440/day x 365 |
@@ -379,7 +544,7 @@ After D^2 optimization, weights are **rescaled via OLS** on the realized varianc
 forecast_sigma_t^2 = beta_0 + beta_1 * sigma_t^2(D^2)
 ```
 
-D^2 acts as a data-driven smoother over RV lags — more flexible than HAR-RV's fixed rolling means (1, 5, 22). OLS rescaling adjusts for bias with only 2 parameters, keeping the model robust on small samples with noisy per-candle RV.
+D^2 acts as a data-driven smoother over RV lags — more flexible than HAR-RV's three rolling means. OLS rescaling adjusts for bias with only 2 parameters, keeping the model robust on small samples with noisy per-candle RV. Inside `predict` the NoVaS lag order grows with the sample size (~n^(1/3)) instead of being fixed at 10.
 
 Multi-step forecast: replace future innovations with sigma^2 (since E[RV] = E[X^2] = sigma^2), then rescale:
 
@@ -424,7 +589,7 @@ The library fits all five models on every call and picks the best by QLIKE. Each
 
 - **GJR-GARCH** — Same idea as EGARCH (red candles increase vol more than green ones) but the effect is milder and simpler: when the return is negative, a bonus term `gamma * epsilon^2` is added to variance. When positive — nothing extra. A binary switch rather than a continuous asymmetry. Common in altcoins and less panic-prone markets.
 
-- **HAR-RV** — Volatility has memory at multiple horizons. The model takes a single timeframe of candles and internally builds three scales: last candle's RV (short, lag 1), rolling average over 5 candles (medium), and rolling average over 22 candles (long). These three components are combined via OLS regression. Works well when different types of participants (scalpers, swing traders, institutions) all influence the same market at different speeds. If your asset has visible "rhythm" across day/week/month — HAR-RV will likely beat GARCH family (sideways, daily patterns).
+- **HAR-RV** — Volatility has memory at multiple horizons. The model takes a single timeframe of candles and internally builds three scales: last candle's RV (short), a medium rolling average, and a long rolling average, combined via OLS regression. The `HarRv` class defaults to the textbook lags (1, 5, 22 — day/week/month in *trading days*), but `predict` chooses the lag horizons from the candle interval itself (one bar / one day / one week in bars, capped by sample size) and picks the winner by QLIKE — the daily-equity convention is not assumed for 24/7 intraday markets. Works well when different types of participants (scalpers, swing traders, institutions) all influence the same market at different speeds.
 
 - **NoVaS** — Volatility drifts or cycles without clear shock-and-decay patterns. Slow trend changes, regime shifts, compression/expansion phases, or "breathing" patterns that don't fit any parametric formula. Model-free: finds weights `a_0...a_p` that make the normalized series as close to Gaussian as possible (minimizes D^2 = skewness^2 + (kurtosis - 3)^2). No assumptions about the distribution shape.
 
@@ -455,7 +620,7 @@ 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`.
+where `z` is the corridor multiplier for the desired two-sided confidence level (returned as `zScore`). It is calibrated on the data: the empirical quantile of the standardized residuals |r/σ| blended with the fitted Student-t(df) quantile, so it needs neither the Gaussian assumption nor a fixed z table. 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:
 
@@ -467,7 +632,7 @@ The previous linear approximation `P · (1 ± sigma)` is a first-order Taylor ex
 
 ### 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:
+`probit(confidence)` computes the inverse of the standard normal CDF (Phi^{-1}). It is the Gaussian limit of the corridor multiplier (the fitted Student-t quantile `studentTProbit(confidence, df)` converges to it as df grows). It converts a two-sided probability to a z-score:
 
 ```
 confidence = P(-z < Z < z),  Z ~ N(0,1)