garch 1.2.4 → 2.0.0

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "garch",
-  "version": "1.2.4",
-  "description": "GARCH and EGARCH volatility models for TypeScript",
-  "funding": {
-    "type": "individual",
-    "url": "http://paypal.me/tripolskypetr"
-  },
-  "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
-  "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": "2.0.0",
+  "description": "GARCH and EGARCH volatility models for TypeScript",
+  "funding": {
+    "type": "individual",
+    "url": "http://paypal.me/tripolskypetr"
+  },
+  "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
+  "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

@@ -68,6 +68,25 @@ interface HarRvParams {
     annualizedVol: number;
     r2: number;
     df: number;
+    /** true when the regression runs on ln RV (betas live in log space). */
+    logSpec?: boolean;
+    /** Residual variance of the log-RV regression (lognormal bias correction). */
+    residualLogVar?: number;
+}
+interface RealizedGarchParams {
+    omega: number;
+    beta: number;
+    gamma: number;
+    /** Measurement-equation intercept: ln RV_t = ξ + ln σ²_t + τ₁z + τ₂(z²−1) + u. */
+    xi: number;
+    tau1: number;
+    tau2: number;
+    /** Std of the measurement noise u — how much the model trusts RV. */
+    sigmaU: number;
+    persistence: number;
+    unconditionalVariance: number;
+    annualizedVol: number;
+    df: number;
 }
 interface NoVaSParams {
     weights: number[];
@@ -83,6 +102,7 @@ interface NoVaSParams {
 interface OptimizerResult {
     x: number[];
     fx: number;
+    /** Iterations of the winning Nelder-Mead run (not summed across multi-start restarts). */
     iterations: number;
     converged: boolean;
 }
@@ -115,6 +135,8 @@ declare class Garch {
     fit(options?: {
         maxIter?: number;
         tol?: number;
+        forgetting?: number;
+        warmStart?: GarchParams;
     }): CalibrationResult<GarchParams>;
     /**
      * Calculate conditional variance series given parameters
@@ -168,11 +190,24 @@ declare class Egarch {
     fit(options?: {
         maxIter?: number;
         tol?: number;
+        forgetting?: number;
+        warmStart?: EgarchParams;
     }): CalibrationResult<EgarchParams>;
     /**
      * Calculate conditional variance series given parameters
      */
     getVarianceSeries(params: EgarchParams): number[];
+    /**
+     * Mean drift of the magnitude term under the fitted dynamics.
+     *
+     * With RV magnitude, E[√(RV/σ²)] ≠ E[|z|]: the in-sample recursion
+     * carries a mean offset α·m̄ per step that ω absorbed during fitting.
+     * A multi-step forecast that drops the α term entirely would therefore
+     * converge to a level systematically below the fitted dynamics.
+     * Returns m̄ = mean(magnitude − E|z|) over the sample (0 for prices-only
+     * input, where magnitude = |z| and the offset is sampling noise).
+     */
+    magnitudeDrift(params: EgarchParams): number;
     /**
      * Forecast variance forward
      *
@@ -200,6 +235,13 @@ interface HarRvOptions {
     shortLag?: number;
     mediumLag?: number;
     longLag?: number;
+    /**
+     * Regress ln RV instead of RV levels (log-HAR, Corsi). Positivity comes
+     * for free (no 1e-20 clamps on negative predictions), residuals are far
+     * closer to homoskedastic, and single RV prints stop dominating the OLS.
+     * Predictions are bias-corrected: E[RV] = exp(ŷ + σ²_ε/2).
+     */
+    logSpec?: boolean;
 }
 /**
  * HAR-RV model (Corsi, 2009)
@@ -223,6 +265,8 @@ declare class HarRv {
     private shortLag;
     private mediumLag;
     private longLag;
+    private logSpec;
+    private lnRv;
     constructor(data: Candle[] | number[], options?: HarRvOptions);
     /**
      * Calibrate HAR-RV via OLS.
@@ -230,6 +274,7 @@ declare class HarRv {
     fit(): CalibrationResult<HarRvParams>;
     /**
      * Internal: compute variance series from beta vector.
+     * For the log spec the prediction is E[RV] = exp(ŷ + σ²_ε/2).
      */
     private getVarianceSeriesInternal;
     /**
@@ -240,7 +285,8 @@ declare class HarRv {
      * Forecast variance forward.
      *
      * Uses iterative substitution: each forecast step feeds back
-     * into the rolling RV components for subsequent steps.
+     * into the rolling RV components for subsequent steps (point forecasts
+     * of ln RV for the log spec, bias-corrected on output).
      */
     forecast(params: HarRvParams, steps?: number): VolatilityForecast;
     /**
@@ -270,7 +316,7 @@ interface GjrGarchOptions {
  * where:
  * - ω (omega) > 0: constant term
  * - α (alpha) ≥ 0: symmetric shock response
- * - γ (gamma) ≥ 0: asymmetric leverage coefficient
+ * - γ (gamma) ≥ −α: asymmetric leverage coefficient (negative = inverted leverage)
  * - β (beta) ≥ 0: persistence
  * - I(r<0) = 1 when return is negative, 0 otherwise
  * - Stationarity: α + γ/2 + β < 1
@@ -290,6 +336,8 @@ declare class GjrGarch {
     fit(options?: {
         maxIter?: number;
         tol?: number;
+        forgetting?: number;
+        warmStart?: GjrGarchParams;
     }): CalibrationResult<GjrGarchParams>;
     /**
      * Calculate conditional variance series given parameters
@@ -313,6 +361,63 @@ declare class GjrGarch {
  */
 declare function calibrateGjrGarch(data: Candle[] | number[], options?: GjrGarchOptions): CalibrationResult<GjrGarchParams>;
 
+interface RealizedGarchOptions {
+    periodsPerYear?: number;
+    maxIter?: number;
+    tol?: number;
+}
+/**
+ * Realized GARCH(1,1) (Hansen, Huang & Shek, 2012), log-linear, φ = 1.
+ *
+ *   r_t = σ_t·z_t,                     z_t ~ standardized t(df)
+ *   ln σ²_t = ω + β·ln σ²_{t−1} + γ·ln RV_{t−1}
+ *   ln RV_t = ξ + ln σ²_t + τ₁·z_t + τ₂·(z²_t − 1) + u_t,   u_t ~ N(0, σ²_u)
+ *
+ * Unlike the RV-in-place-of-ε² hybrids, the measurement equation estimates
+ * the bias (ξ) and noise (σ_u) of the realized measure inside the joint
+ * likelihood: RV information is weighted by how trustworthy it actually is,
+ * and leverage enters through τ₁. Stationarity: β + γ < 1 (with φ = 1).
+ */
+declare class RealizedGarch {
+    private returns;
+    private lnRv;
+    private periodsPerYear;
+    private initialVariance;
+    constructor(data: Candle[] | number[], options?: RealizedGarchOptions);
+    /**
+     * Calibrate by joint MLE over returns and the realized measure.
+     */
+    fit(options?: {
+        maxIter?: number;
+        tol?: number;
+        forgetting?: number;
+        warmStart?: RealizedGarchParams;
+    }): CalibrationResult<RealizedGarchParams>;
+    /**
+     * Conditional variance series (data scale). σ²_t is driven by RV_{t−1}
+     * through the log recursion — no look-ahead.
+     */
+    getVarianceSeries(params: RealizedGarchParams): number[];
+    /**
+     * Forecast variance forward. One step uses the actual last RV; further
+     * steps substitute E[ln RV_t] = ξ + ln σ²_t, giving the reduced recursion
+     * ln σ²_{t+h} = (ω + γξ) + (β + γ)·ln σ²_{t+h−1}.
+     */
+    forecast(params: RealizedGarchParams, steps?: number): VolatilityForecast;
+    /**
+     * Get the return series.
+     */
+    getReturns(): number[];
+    /**
+     * Get initial variance estimate.
+     */
+    getInitialVariance(): number;
+}
+/**
+ * Convenience function to calibrate Realized GARCH from candles or prices.
+ */
+declare function calibrateRealizedGarch(data: Candle[] | number[], options?: RealizedGarchOptions): CalibrationResult<RealizedGarchParams>;
+
 interface NoVaSOptions {
     periodsPerYear?: number;
     lags?: number;
@@ -352,6 +457,7 @@ declare class NoVaS {
     fit(options?: {
         maxIter?: number;
         tol?: number;
+        warmWeights?: number[];
     }): CalibrationResult<NoVaSParams>;
     /**
      * Internal: compute variance series from D² weight vector.
@@ -384,6 +490,15 @@ declare class NoVaS {
  */
 declare function calibrateNoVaS(data: Candle[] | number[], options?: NoVaSOptions): CalibrationResult<NoVaSParams>;
 
+/**
+ * Validate OHLC integrity. Garbage candles (NaN, non-positive prices,
+ * high < low) otherwise propagate silently as NaN through every estimator.
+ */
+declare function validateCandles(candles: Candle[]): void;
+/**
+ * Linear-interpolation quantile of a pre-sorted (ascending) sample.
+ */
+declare function empiricalQuantile(sortedAsc: number[], p: number): number;
 /**
  * Calculate log returns from candles
  */
@@ -472,6 +587,28 @@ declare function studentTNegLL(returns: number[], varianceSeries: number[], df:
  * Converges to √(2/π) as df → ∞ (Gaussian limit).
  */
 declare function expectedAbsStudentT(df: number): number;
+/**
+ * Regularized incomplete beta function I_x(a, b).
+ */
+declare function incompleteBeta(x: number, a: number, b: number): number;
+/**
+ * CDF of the (raw, unstandardized) Student-t distribution with df degrees
+ * of freedom: P(T ≤ t).
+ */
+declare function studentTCdf(t: number, df: number): number;
+/**
+ * Two-sided quantile of the STANDARDIZED Student-t distribution
+ * (unit variance). The t-analog of probit(): returns z such that
+ * P(|Z| ≤ z) = confidence when Z ~ t(df) scaled to variance 1.
+ *
+ * This is what price corridors must use when the model was fitted with
+ * Student-t innovations: with fat tails (small df) the Gaussian probit
+ * makes 68% bands too wide and 99% bands dangerously narrow.
+ *
+ * Falls back to probit() for df > 1000 (where the difference from the
+ * Gaussian quantile is < 0.3% even at 99%) or df ≤ 2 (variance undefined).
+ */
+declare function studentTProbit(confidence: number, df: number): number;
 /**
  * 1D grid search for optimal df that minimizes Student-t neg-LL.
  * Used by HAR-RV and NoVaS where df is profiled after main optimization.
@@ -497,6 +634,14 @@ declare function qlike(varianceSeries: number[], rv: number[]): number;
 declare function probit(confidence: number): number;
 
 type CandleInterval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '6h' | '8h';
+type WarningCode = 'LOW_SAMPLE' | 'NOT_CONVERGED' | 'HIGH_PERSISTENCE' | 'DEGENERATE_VARIANCE' | 'RESIDUAL_AUTOCORRELATION' | 'DATA_GAPS' | 'INTERVAL_MISMATCH';
+interface PredictionWarning {
+    code: WarningCode;
+    /** Plain-language explanation with a suggested action. */
+    message: string;
+    /** true when this warning alone makes the forecast unreliable. */
+    critical: boolean;
+}
 interface PredictionResult {
     /** Reference price used to compute the corridor (last close or the value passed as `currentPrice`). */
     currentPrice: number;
@@ -510,28 +655,178 @@ interface PredictionResult {
     upperPrice: number;
     /** Lower price band: `currentPrice · exp(-z·σ)`. Always positive. */
     lowerPrice: number;
-    /** Volatility model auto-selected by QLIKE. */
-    modelType: 'garch' | 'egarch' | 'gjr-garch' | 'har-rv' | 'novas';
-    /** `true` when the model converged, persistence < 0.999, and Ljung-Box p-value ≥ 0.05. */
+    /** Top-weight member of the volatility model combination (selected by out-of-sample QLIKE). */
+    modelType: 'garch' | 'egarch' | 'gjr-garch' | 'realized-garch' | 'har-rv' | 'novas';
+    /** Student-t degrees of freedom profiled on scale-corrected residuals. */
+    df: number;
+    /**
+     * Average corridor multiplier, (zScoreUp + zScoreDown) / 2 — kept for
+     * backward compatibility. The bands themselves are asymmetric; use
+     * zScoreUp/zScoreDown to reconstruct them exactly.
+     */
+    zScore: number;
+    /** Upper-tail multiplier: `upperPrice = currentPrice · exp(+zScoreUp · sigma)`. */
+    zScoreUp: number;
+    /** Lower-tail multiplier: `lowerPrice = currentPrice · exp(−zScoreDown · sigma)`. */
+    zScoreDown: number;
+    /** `true` when no critical warning fired (model converged, persistence < 0.999, Ljung-Box p ≥ 0.05, non-degenerate variance). */
     reliable: boolean;
+    /**
+     * Everything the pipeline noticed, in plain language: why `reliable` is
+     * false (critical warnings) plus non-critical data quality notes.
+     */
+    warnings: PredictionWarning[];
+    /** Combination weights per model family (out-of-sample QLIKE softmax), summing to 1. */
+    modelWeights: Partial<Record<PredictionResult['modelType'], number>>;
+    /** `true` when a significant diurnal volatility profile was detected and removed before fitting. */
+    seasonalityDetected: boolean;
+}
+interface PredictOptions {
+    /** Reference price for the corridor; defaults to the last close. */
+    currentPrice?: number | null;
+    /** Two-sided probability in (0,1). Default ≈0.6827 (±1σ). */
+    confidence?: number;
+}
+interface DataIssue {
+    code: 'TOO_FEW_CANDLES' | 'INVALID_OHLC' | 'UNSORTED' | 'DUPLICATE_TIMESTAMPS' | 'LOW_SAMPLE' | 'DATA_GAPS' | 'INTERVAL_MISMATCH' | 'FLAT_CANDLES';
+    message: string;
+    severity: 'error' | 'warning';
+}
+interface DataReport {
+    /** false when any error-severity issue is present (predict would throw). */
+    ok: boolean;
+    issues: DataIssue[];
+    recommendedCandles: number;
+}
+/**
+ * Pre-flight data check with plain-language, actionable messages: run it on
+ * a new data source before wiring it into predict. Errors are conditions
+ * predict would throw on; warnings degrade quality but do not block.
+ */
+declare function checkData(candles: Candle[], interval: CandleInterval): DataReport;
+interface Seasonality {
+    /** Variance factor per intraday bucket, sample-weighted mean 1. */
+    factors: number[];
+    /** Bucket of return index t (i.e. candle t+1); also valid for future t. */
+    bucketOfReturn: (t: number) => number;
 }
+/**
+ * Diurnal variance profile from per-candle Parkinson RV.
+ *
+ * Intraday markets have a strong time-of-day volatility pattern (sessions,
+ * funding, weekends). A GARCH-family fit smears it into average persistence,
+ * so corridors are systematically too narrow in active hours and too wide in
+ * quiet ones. Factors are estimated per intraday bucket (≤24 per day, bars
+ * grouped for sub-hour intervals), circularly smoothed, shrunk toward 1 by
+ * bucket support, and gated by a χ² significance test against the RV
+ * sampling noise (inflated for volatility clustering) — pure-GARCH data
+ * without seasonality returns null and the pipeline is unchanged.
+ *
+ * Timestamps (ms or s), when present on every candle, anchor buckets to
+ * real time of day and survive gaps; otherwise buckets are positional and
+ * assume contiguous bars.
+ */
+declare function computeSeasonality(candles: Candle[], interval: CandleInterval): Seasonality | null;
+/**
+ * Rescale each candle's log-moves by 1/√f(bucket) so the deseasonalized
+ * series has a flat diurnal profile. Gaps (open vs prev close) are scaled
+ * with the same factor; OHLC ordering is preserved (monotone log map).
+ */
+declare function deseasonalizeCandles(candles: Candle[], season: Seasonality): Candle[];
+/**
+ * Cached calibration state threaded between rolling refits: previous
+ * optima become warm starts with a reduced multi-start budget, and the
+ * HAR spec search collapses to the previously selected configuration.
+ */
+interface WarmState {
+    garch?: GarchParams;
+    garchForget?: GarchParams;
+    egarch?: EgarchParams;
+    gjr?: GjrGarchParams;
+    rgarch?: RealizedGarchParams;
+    harLags?: [number, number, number];
+    harLog?: boolean;
+    novasWeights?: number[];
+}
+/**
+ * Stateful predictor for rolling use (bots, backtests): each subsequent
+ * predict/predictRange warm-starts every optimizer from the previous
+ * window's optimum with a reduced multi-start budget — same math, a
+ * fraction of the cost. State is per-instrument: do not share one
+ * predictor across symbols.
+ */
+declare function createPredictor(interval: CandleInterval): {
+    predict: (candles: Candle[], currentPriceOrOptions?: number | null | PredictOptions, confidence?: number) => PredictionResult;
+    predictRange: (candles: Candle[], steps: number, currentPriceOrOptions?: number | null | PredictOptions, confidence?: number) => PredictionResult;
+};
 /**
  * Forecast expected price range for t+1 (next candle).
  *
- * Auto-selects the best volatility model via QLIKE.
- * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
+ * Combines all volatility models weighted by out-of-sample QLIKE,
+ * deseasonalizes the diurnal variance profile when one is present,
+ * rescales the variance to the return scale (Var(r/σ) = 1), and builds
+ * bands P·exp(±z·σ) where z is calibrated on the data itself: the
+ * empirical |z| quantile of the standardized residuals blended with the
+ * fitted Student-t quantile as the tail runs out of observations (see
+ * corridorZ). Empirical coverage tracks the requested confidence without
+ * assuming a distributional shape.
  * @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.
+ *   Common values: 0.90, 0.95, 0.99.
  */
-declare function predict(candles: Candle[], interval: CandleInterval, currentPrice?: number | null, confidence?: number): PredictionResult;
+declare function predict(candles: Candle[], interval: CandleInterval, currentPriceOrOptions?: number | null | PredictOptions, confidence?: number): PredictionResult;
 /**
  * Forecast expected price range over multiple candles.
  *
- * Cumulative σ = √(σ₁² + σ₂² + ... + σₙ²) — total expected move over N periods.
- * Uses log-normal price bands: P·exp(±z·σ), where z = probit(confidence).
+ * Cumulative σ = √(σ₁² + σ₂² + ... + σₙ²) — total expected move over N
+ * periods, with each step's variance carrying its own seasonal factor.
+ * Uses log-normal price bands P·exp(±z·σ) where z is calibrated at the
+ * requested horizon: the empirical quantile of |h-step standardized sums|
+ * from the sample itself, blended with the model-implied quantile simulated
+ * through the fitted recursions (volatility feedback and fat-tail decay
+ * included).
  * @param confidence — two-sided probability in (0,1). Default ≈0.6827 (±1σ).
+ * @param steps — horizon in candles, 1 ≤ steps ≤ candles.length.
+ */
+declare function predictRange(candles: Candle[], interval: CandleInterval, steps: number, currentPriceOrOptions?: number | null | PredictOptions, confidence?: number): PredictionResult;
+interface BacktestStats {
+    /** Number of test candles whose close landed inside the predicted corridor. */
+    hits: number;
+    /** Number of walk-forward predictions made. */
+    total: number;
+    /** Empirical coverage in percent (0–100). Compare against `confidence · 100`. */
+    hitRate: number;
+    /** Statistical judgment of the coverage against the nominal confidence (Kupiec POF test). */
+    verdict: 'well-calibrated' | 'too-narrow' | 'too-wide' | 'inconclusive';
+    /** Kupiec test p-value: probability of a coverage gap this large under correct calibration. */
+    pValue: number;
+    /** Plain-language interpretation of the verdict with the numbers filled in. */
+    message: string;
+}
+/**
+ * Kupiec (1995) proportion-of-failures test: is the observed hit rate
+ * statistically consistent with the nominal confidence, given how many
+ * walk-forward points there are? A raw hitRate of 63% vs nominal 68% means
+ * nothing without n — this answers "failure or noise" directly.
+ */
+declare function kupiecTest(hits: number, total: number, confidence: number): Pick<BacktestStats, 'verdict' | 'pValue' | 'message'>;
+/**
+ * Walk-forward calibration statistics for predict.
+ *
+ * Refits the model on a rolling window (75% of candles, min MIN_CANDLES)
+ * and checks whether the next close lands inside the predicted corridor.
+ * A well-calibrated tool has hitRate ≈ confidence·100.
+ *
+ * Every refit costs a full multi-model calibration, so by default the test
+ * points are subsampled to at most ~100 refits (stride grows with the test
+ * span). Pass `stride: 1` to evaluate every candle when runtime is not a
+ * concern, or any positive stride to control the trade-off yourself.
+ * Throws if not enough candles for the given interval.
+ * @param confidence — two-sided probability in (0,1) for the prediction band.
+ *   Default ≈0.6827 (±1σ).
  */
-declare function predictRange(candles: Candle[], interval: CandleInterval, steps: number, currentPrice?: number | null, confidence?: number): PredictionResult;
+declare function backtestStats(candles: Candle[], interval: CandleInterval, confidence?: number, options?: {
+    stride?: number;
+}): BacktestStats;
 /**
  * Walk-forward backtest of predict.
  *
@@ -544,6 +839,30 @@ declare function predictRange(candles: Candle[], interval: CandleInterval, steps
  */
 declare function backtest(candles: Candle[], interval: CandleInterval, confidence?: number, requiredPercent?: number): boolean;
 
+/**
+ * Typed error hierarchy so bot code can branch on error class instead of
+ * parsing message strings.
+ *
+ *   try { predict(candles, '1h') }
+ *   catch (e) {
+ *     if (e instanceof NotEnoughDataError) await fetchMoreCandles();
+ *     else if (e instanceof BadDataError) alertDataPipeline(e.message);
+ *     else throw e;
+ *   }
+ */
+declare class GarchError extends Error {
+    constructor(message: string);
+}
+/** The sample is too short for the requested interval/model. Fetch more candles. */
+declare class NotEnoughDataError extends GarchError {
+}
+/** The candles themselves are broken: invalid OHLC, unsorted or duplicated timestamps. Fix the data pipeline. */
+declare class BadDataError extends GarchError {
+}
+/** A call argument is out of range or of the wrong shape (interval, confidence, steps, currentPrice). Fix the call site. */
+declare class InvalidArgumentError extends GarchError {
+}
+
 declare function nelderMead(fn: (x: number[]) => number, x0: number[], options?: {
     maxIter?: number;
     tol?: number;
@@ -556,7 +875,15 @@ declare function nelderMeadMultiStart(fn: (x: number[]) => number, x0: number[],
     maxIter?: number;
     tol?: number;
     restarts?: number;
+    /**
+     * Additional explicit starting points, each run through a full NM pass.
+     * The perturbation restarts below scale x0 multiplicatively, so they
+     * preserve its shape — basins whose shape differs from x0 (e.g. far-lag
+     * weight structures) are unreachable from x0 alone and must be seeded
+     * explicitly.
+     */
+    extraStarts?: 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, 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 };
+export { BadDataError, EXPECTED_ABS_NORMAL, Egarch, Garch, GarchError, GjrGarch, HarRv, InvalidArgumentError, NoVaS, NotEnoughDataError, RealizedGarch, backtest, backtestStats, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, calibrateGjrGarch, calibrateHarRv, calibrateNoVaS, calibrateRealizedGarch, checkData, checkLeverageEffect, computeSeasonality, createPredictor, deseasonalizeCandles, empiricalQuantile, expectedAbsStudentT, garmanKlassVariance, incompleteBeta, kupiecTest, ljungBox, logGamma, nelderMead, nelderMeadMultiStart, perCandleParkinson, predict, predictRange, probit, profileStudentTDf, qlike, sampleVariance, sampleVarianceWithMean, studentTCdf, studentTNegLL, studentTProbit, validateCandles, yangZhangVariance };
+export type { BacktestStats, CalibrationResult, Candle, CandleInterval, DataIssue, DataReport, EgarchOptions, EgarchParams, GarchOptions, GarchParams, GjrGarchOptions, GjrGarchParams, HarRvOptions, HarRvParams, LeverageStats, NoVaSOptions, NoVaSParams, OptimizerResult, PredictOptions, PredictionResult, PredictionWarning, RealizedGarchOptions, RealizedGarchParams, Seasonality, VolatilityForecast, WarmState, WarningCode };