@krzysztofsztompka/garch 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,8 @@ npm install @krzysztofsztompka/garch
 ```
 
 Node ≥ 20. The core (`@krzysztofsztompka/garch`) runs anywhere; the worker pool
-(`@krzysztofsztompka/garch/node`) needs Node's `worker_threads`.
+comes as `@krzysztofsztompka/garch/node` (Node's `worker_threads`) and
+`@krzysztofsztompka/garch/web` (Web Workers, ES modules only).
 
 ## Quick start
 
@@ -40,7 +41,10 @@ What it does not do, deliberately:
 - **No prices and no percent.** It takes returns in whatever units it is given.
 - **No interpretation.** When σ̂ is worth quoting, or what a regime means, is the caller's.
 - **No trimming.** `quantizedUntil` says where a coarse-grid stretch of history ends; whether to fit from there is the caller's.
-- **No EGARCH with Student-t innovations.** Its expected variance two steps ahead is infinite (below).
+- **No EGARCH with Student-t or skewed-t innovations.** Its expected variance two steps ahead is infinite (below).
+- **No AR or ARMA mean.** The mean is a constant or zero. Daily returns have next to no autocorrelation to model; a caller who needs it can filter the returns first and fit with `mean: 'zero'`.
+- **No GED innovations.** Normal, t and skewed t cover thin tails, fat tails and a skew; GED adds a tail shape between normal and t that daily equity returns rarely ask for.
+- **No GARCH(p, q) beyond (1, 1).** Higher orders rarely beat (1, 1) out of sample, and they need a different stationarity parameterisation; every model here is (1, 1).
 
 ## The model
 
@@ -49,8 +53,10 @@ What it does not do, deliberately:
     r_t = μ + e_t,   e_t ~ N(0, s_t)
     s_t = ω + α·e²_{t−1} + γ·e²_{t−1}·[e_{t−1} < 0] + β·s_{t−1}      (γ = 0 for garch)
 
+- **A zero mean** (`mean: 'zero'`, `arch`'s `mean='Zero'`) holds μ at 0 for returns already demeaned; every model takes it, and so do the walk-forward, the pool and the weighted forecast. It matches `arch` on the fixture series.
 - **Backcast as in `arch`.** The recursion starts from an exponentially weighted (0.94) mean of the first 75 squared residuals.
 - **Analytic forecasts.** s_{T+k} = ω + (α + γ/2 + β)·s_{T+k−1}.
+- **AIC and BIC** as `arch` computes them, −2·ln L + 2k and −2·ln L + k·ln n, with k the free parameters (`parameterCount`): μ, ω, α, β, plus γ for gjr and egarch, plus ν for t unless it is held on a bound.
 - **Robust standard errors.** Bollerslev–Wooldridge, `arch`'s `cov_type="robust"`: analytic scores and a Hessian taken by differencing the analytic gradient.
 
 ### Student-t innovations (`dist: 't'`)
@@ -64,6 +70,20 @@ parameter with its analytic gradient and robust standard error.
 - **A ν the data push past a bound is held there.** Free, the logit of ν runs off and the fit never converges. The fit is refitted with ν fixed on the bound (the constrained optimum) and reports `nuBound: 'lower' | 'upper'`. A held ν has no standard error.
 - **Exact-zero returns break it.** Prices recorded on a coarse grid make most days an exact zero: cents on a stock worth $0.08 split-adjusted, or a penny stock's cents times a 1:100 reverse split. On an exact zero the variance can run to 0 while the likelihood rises without bound. The normal likelihood punishes that on the next non-zero day (e²/s); the t likelihood only logarithmically, so the fit degenerates to ω ≈ 0 and μ ≈ 0, **and can still report `converged`**. `quantizedUntil(returns)` returns the index after the last 250-return window with more than 20 % exact zeros; fit t from there.
 
+### Skewed-t innovations (`dist: 'skewt'`)
+
+Hansen's skewed t, `arch`'s `SkewStudent`: standardised to mean 0 and variance
+1, with ν (`arch`'s η) and λ ∈ (−1, 1); λ < 0 leans the mass left, a fatter
+loss tail. Each side of the density is half a standardised t, so its CDF,
+quantile and partial moments E[zᵏ·1{z < x}] are closed forms over the
+incomplete beta; they agree with `arch`'s to 1e-14. The gradient is analytic
+in λ and ν as well, λ has a robust standard error and p-value, and ν has the
+same floor and bound handling as under t.
+
+- **GJR's asymmetry under a skew.** A down move's share of a unit shock's variance, κ = E[z²·1{z < 0}], is ½ only for a symmetric innovation; under a skewed t it is computed exactly (`downShare`, `skewDownShare`). `persistence` and the forecast use κ: s_{T+k} = ω + (α + κγ + β)·s_{T+k−1}. `arch` uses ½ there whatever the distribution, so for a skewed GJR its analytic forecast and this one differ by that much; the simulated paths here agree with this one. The search space keeps `arch`'s constraint α + γ/2 + β < 1.
+- **Against `arch`** on SPY: garch and gjr fits to ~1e-5, with an equal or higher likelihood, and λ's and γ's p-values within 2 %.
+- **VaR and ES** take λ (`tailRisk({ ..., nu, lambda })`), and `simulate` draws skewed-t innovations when the parameters carry λ.
+
 ### EGARCH (`model: 'egarch'`)
 
 `arch`'s `vol="EGARCH", p=1, o=1, q=1` with normal innovations:
@@ -74,9 +94,39 @@ parameter with its analytic gradient and robust standard error.
 - **The recursion starts from ln of the backcast**, with no shock term at t = 0, as in `arch`. `GarchFit.backcast` holds that log.
 - **Parameter space.** β = σ(x2) ∈ (0, 1); ω = (1 − β)·(ln var(r) + x1); α and γ are free. `arch` lets β run in (−1, 1); a negative β is left out here. The gradient is analytic, through the recursion of d ln s.
 - **The forecast is exact, not simulated.** E[s_{T+k}] = exp(m_k)·Π_{j<k−1} E[exp(βʲ·g(z))], with m_k = ω + β·m_{k−1}. Under the normal, E[exp(a|z| + bz)] = e^{(a+b)²/2}Φ(a+b) + e^{(a−b)²/2}Φ(a−b). Under Student-t that expectation is infinite for every a > 0, which is why a t EGARCH is refused (`GarchInputError`).
-- **Against `arch` 8.0.0** (`test/fixtures/arch-egarch-2026-10-01.json`): the same optimum to ~1e-5 in α, γ, β, and an equal or slightly higher log-likelihood. γ's robust p-value agrees within 1 %. The closed-form forecast agrees with `arch`'s 200 000 simulated paths to 0.01 % and 0.24 % at 20 steps.
+- **Against `arch` 8.0.0** (`test/fixtures/arch-egarch-2026-10-01.json`): the same optimum to ~1e-5 in α, γ, β, and an equal or slightly higher log-likelihood. γ's robust p-value agrees within 1 %. The closed-form forecast agrees with `arch`'s 200 000 simulated paths (seeded) to 0.02 % and 0.08 % at 20 steps.
 - **Its walk-forward baseline is symmetric GARCH,** like GJR's: is the asymmetry worth it?
 
+### Simulation
+
+`simulate` runs the model's own recursion forward: `paths` paths of `steps`
+returns, from where a fit stands (its last variance and residual, so step 1's
+variance is the one-step forecast) or from the unconditional variance. The
+innovations are normal, or Student-t scaled to unit variance when the
+parameters carry ν; an EGARCH with t is refused, as in fitting. One seeded
+stream (xoshiro128**) feeds every path, so a seed gives the same paths on any
+platform. The paths' mean variance converges to `forecastVariance`.
+
+### Residual diagnostics
+
+`standardizedResiduals(fit, returns)` gives z_t = (r_t − μ)/√s_t. `ljungBox`
+(on z for the mean, on z² for the variance) and `archLm` (Engle's LM test on
+z) say whether the model left anything behind; each returns the statistic, its
+χ² degrees of freedom and the p-value. They follow statsmodels'
+`acorr_ljungbox` and `het_arch` and agree with them on the fixture series to
+1e-3; `chiSquareSurvival` agrees with scipy to 1e-12.
+
+### Value at risk
+
+VaR and ES are positive losses in the returns' units at a tail probability
+`level` (0.01 for 99 %). `tailRisk` gives the one-step answer in closed form
+from μ, s_{T+1} and the innovations (normal, or standardised t with ν); its
+quantiles and tail means agree with scipy. Over several steps the cumulative
+return under GARCH is not normal, so `simulatedTailRisk` reads VaR and ES off
+`simulate`'s paths. `varBacktest` walks a one-step VaR forward and
+`coverageTest` grades the violations: Kupiec's unconditional coverage,
+Christoffersen's independence, and both together.
+
 ## The optimiser, and why it has six starts
 
 BFGS with an analytic gradient runs in an unconstrained space where every point
@@ -115,8 +165,28 @@ tasks share one deadline: past it, or on one task's refusal, its queued tasks
 are dropped and its running workers terminated, and the pool carries on. The
 heaviest segments (the longest train windows) are dispatched first.
 
-Measured on an i7-13700K (23 workers), one core → pool: S&P 500 (14 k returns)
-GJR 93 s → 10 s, GARCH 46 s → 5 s; SPY GJR 36 s → 4 s.
+`npm run bench` measures it on SPY's closes from the `arch` fixture (8 469
+returns, horizon 20) and asserts the pool's answer equals the in-process one.
+On an i7-13700K, Node 24, 23 workers, one core → pool:
+
+| job | one core | pool |
+|---|---|---|
+| garch | 15.8 s | 2.3 s |
+| gjr | 42.4 s | 4.0 s |
+| egarch | 51.7 s | 3.9 s |
+| weighted (`-- --weighted`) | 122 s | 11.2 s |
+
+### In the browser
+
+`@krzysztofsztompka/garch/web` is the same pool on Web Workers: `GarchWebPool`
+(default: every logical core but one) and the same calls —
+`volatilityForecastInWorkers`, `fitsAtInWorkers`, `weightedForecastInWorkers`,
+`runInWorker` — with the in-process answer. The worker is started as
+`new Worker(new URL('./worker-web.js', import.meta.url), { type: 'module' })`,
+written out literally, so Vite and webpack bundle it without configuration;
+both were checked in Chrome. A bundler that needs the worker its own way passes
+`new GarchWebPool(size, () => new Worker(...))`. Node's pool and this one share
+one implementation of the queue, deadline and cancellation (`WorkerPool`).
 
 ## Several models, weighted by their past loss
 
@@ -156,15 +226,30 @@ npm `garch`'s variance forecast collapses to ≈ 0 at single origins (QLIKE 10¹
 ## API
 
 ```ts
-import { egarchForecast, fitGarch, forecastVariance, quantizedUntil, walkForwardValidation, volatilityForecast, fitsAt } from '@krzysztofsztompka/garch';
+import { archLm, egarchForecast, fitGarch, forecastVariance, ljungBox, quantizedUntil, simulate, simulatedTailRisk, standardizedResiduals, tailRisk, varBacktest, walkForwardValidation, volatilityForecast, fitsAt } from '@krzysztofsztompka/garch';
 import { fitsAtInWorkers, runInWorker, volatilityForecastInWorkers, weightedForecastInWorkers } from '@krzysztofsztompka/garch/node';
 
 const fit = fitGarch(returns, { model: 'gjr', inference: true });
 fit.modes;                     // every optimum reached, best first
+fit.aic; fit.bic;              // as arch reports them; a ν held on a bound is not counted
 fitGarch(returns, { model: 'egarch', inference: true });          // γ < 0: leverage; normal innovations only
+fitGarch(returns, { model: 'gjr', mean: 'zero' });                // μ held at 0
+fitGarch(returns, { model: 'gjr', dist: 'skewt', inference: true }); // → params.nu, params.lambda; λ < 0: a fatter loss tail
 fitGarch(returns.slice(quantizedUntil(returns)), { dist: 't' });   // Student-t on the fine-grained history
 // → params.nu, nuBound: 'lower' | 'upper' | null
 
+// paths forward from where the fit stands (seeded); a FitAt from fitsAt spreads in as it is
+simulate({ model: 'gjr', params: fit.params, lastVariance: fit.conditionalVariance.at(-1), lastResidual: fit.lastResidual,
+           steps: 20, paths: 10_000, seed: 1 });   // → { returns, variance }: Float64Array per path
+
+const z = standardizedResiduals(fit, returns);
+ljungBox(z.map((v) => v * v), 10);   // → { statistic, df, pValue }: ARCH left in the residuals?
+archLm(z, 10);
+
+tailRisk({ mean: fit.params.mu, variance: forecastVariance(fit, 1)[0], nu: fit.params.nu, level: 0.01 });
+simulatedTailRisk(simulate({ ... , steps: 10, paths: 100_000, seed: 1 }), 0.01);   // 10-day VaR, ES
+varBacktest(returns, { model: 'gjr', dist: 't', level: 0.01, step: 1 });          // → violations, rate, Kupiec, Christoffersen
+
 // Node only: the walk-forward's segments across a pool of workers — the in-process answer, faster
 await volatilityForecastInWorkers({ returns, model: 'gjr', horizon: 20, rivalsWithin: 1.92 }, { timeoutMs: 120_000 });
 await fitsAtInWorkers({ returns, ends: [999, 1499] });
@@ -184,19 +269,34 @@ reject with one of three errors, so a caller can word each:
 
 `npm test` compiles `src/` and `test/` with tsc and runs them with `node --test`.
 There is no test framework dependency.
+`npm run coverage` (Node ≥ 22.8) adds Node's own coverage of the compiled
+code and fails under 95 % of lines, 85 % of branches or 80 % of functions; CI
+runs it on Node 22 and 24. Code that runs only inside a worker is counted where
+the tests also run it in-process.
 
 - **The analytic gradient** matches its finite difference.
 - **Simulated paths.** Parameters are recovered on simulated GARCH and GJR paths. A real leverage term is significant and an absent one is not.
 - **Every fit is a valid, stationary model.** Inputs that cannot be fitted are refused.
 - **Forecasts** decay to the unconditional variance.
 - **Walk-forward windows** never leak from test into train.
-- **Against `arch` (frozen 2026-09-25).** `test/fixtures/arch-2026-09-25.json` holds real IOVA and SPY closes and `arch`'s own answers. The package must match the parameters and σ̂ to 1e-3 / 1e-4, γ's p-value to 2 %, and IOVA's walk-forward QLIKE to 1e-3.
+- **Simulation.** A seed gives the same paths; the paths' mean variance matches the analytic forecast for GJR (normal and t) and EGARCH, and their innovations have unit variance.
+- **Value at risk.** Normal and t quantiles, VaR and ES against scipy; the one-step VaR read off simulated paths; Kupiec and Christoffersen statistics against a hand computation; a walked-forward VaR covers at its level when the model is the truth.
+- **Residual diagnostics.** Ljung–Box and ARCH-LM against statsmodels on the fixture series; the χ² tail against scipy; ARCH found in a GARCH path and none left in its standardised residuals.
+- **Against `arch`.** `test/fixtures/arch-2026-09-25.json` holds real IOVA and SPY closes (to 2026-09-23) and `arch`'s own answers. The package must match the parameters and σ̂ to 1e-3 / 1e-4, γ's p-value to 2 %, and IOVA's walk-forward QLIKE to 1e-3.
+- **The fixtures are regenerated, not hand-written.** `scripts/arch-fixtures/generate.py` reads the closes from the fixture and rewrites `arch`'s answers in both files, with the versions in its `requirements.txt` (`arch` 8.0.0) and a seeded simulation, recording both in each file's `source`:
+
+  ```bash
+  python3 -m venv .venv && .venv/bin/pip install -r scripts/arch-fixtures/requirements.txt
+  .venv/bin/python scripts/arch-fixtures/generate.py
+  ```
 - **Worker round trip.** The same answer as in-process, an input refusal kept as an input refusal, and a timeout that terminates the worker.
 - **The modes.** Best first, the fit being the first; the warm start's optimum marked; rivals only within the asked distance.
 - **Student-t.** The gradient against finite differences, ν included. ν is recovered on a simulated t-GARCH path. A ν below the floor is held and converges, and its standard error is NaN. Robust SE come with a free ν.
+- **Skewed t.** `arch`'s `SkewStudent` quantiles and partial moments to 1e-12; the gradient against finite differences, ν and λ included; ν and λ recovered on a simulated path; SPY's garch and gjr fits against `arch`'s; the skewed VaR and ES against the model's own paths; the simulated variance against the forecast with the exact down share.
 - **Weighting.** Equal weights before the burn-in; the better model dominates after it; changing a forecast whose window ends after an origin does not move that origin's weights; the pool's answer equals the in-process one.
 - **EGARCH.** The gradient against finite differences. A simulated path's parameters, leverage sign included. The closed-form forecast against its own Monte Carlo. `arch` 8.0.0's optimum, γ p-value and simulated forecast. A t EGARCH refused.
 - **Quantized history.** On IOVA's frozen closes: the cut lands where the reverse-split cents end, t degenerates before it (ω ≈ 0 while `converged`), and fits cleanly after it.
+- **The web pool.** Through a Web Worker made of a worker thread: the walk-forward identical to in-process, an input refusal and a deadline carried as on Node.
 - **The pool.** The walk-forward and `fitsAt` bit-identical to in-process on pools of 1 and 3 workers; one refused job fails its whole call; the pool keeps working after a call timed out.
 
 ## Build
@@ -205,6 +305,15 @@ There is no test framework dependency.
 npm install && npm run build     # → dist/cjs and dist/esm, each with .d.ts
 ```
 
+## Releasing
+
+Move `CHANGELOG.md`'s `Unreleased` entries under the new version, set
+`package.json`'s version to match, commit, then push a tag `v<version>`. The
+`release` workflow refuses a tag that differs from the version or has no
+changelog section; otherwise it tests, publishes to npm with provenance and
+makes the GitHub Release from that section. npm trusts the workflow as a
+trusted publisher (`uhlryk/garch`, `release.yml`), so no token is stored.
+
 ## Licence
 
 MIT

package/dist/cjs/diagnostics.d.ts

@@ -0,0 +1,29 @@
+import type { GarchFit } from './fit.js';
+/**
+ * Is anything left for the model to explain? A fitted model's standardised
+ * residuals z_t = (r_t − μ) / √s_t should be serially uncorrelated, and so
+ * should z²_t — what remains of an ARCH effect shows up there.
+ */
+/** z_t = (r_t − μ) / √s_t for every observation of the fit. */
+export declare function standardizedResiduals(fit: GarchFit, returns: ArrayLike<number>): Float64Array;
+export type TestResult = {
+    readonly statistic: number;
+    /** Degrees of freedom of the χ² it is referred to. */
+    readonly df: number;
+    readonly pValue: number;
+};
+/** P(χ²_df > x), computed in the upper tail (no 1 − P cancellation for a large statistic). */
+export declare function chiSquareSurvival(x: number, df: number): number;
+/**
+ * Ljung–Box Q = n(n + 2)·Σ_{k ≤ lags} ρ̂²_k / (n − k) against χ²(lags − modelDf),
+ * as statsmodels' `acorr_ljungbox` (autocorrelations of the demeaned series
+ * over its total sum of squares). Run it on z for the mean, on z² for what
+ * remains of the variance dynamics.
+ */
+export declare function ljungBox(series: ArrayLike<number>, lags: number, modelDf?: number): TestResult;
+/**
+ * Engle's ARCH-LM test: e²_t regressed on a constant and e²_{t−1} … e²_{t−lags};
+ * LM = (n − lags)·R² against χ²(lags), as statsmodels' `het_arch`. On the
+ * standardised residuals, a small p-value says the model left ARCH behind.
+ */
+export declare function archLm(series: ArrayLike<number>, lags: number): TestResult;

package/dist/cjs/diagnostics.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standardizedResiduals = standardizedResiduals;
+exports.chiSquareSurvival = chiSquareSurvival;
+exports.ljungBox = ljungBox;
+exports.archLm = archLm;
+const inference_js_1 = require("./inference.js");
+const special_js_1 = require("./special.js");
+/**
+ * Is anything left for the model to explain? A fitted model's standardised
+ * residuals z_t = (r_t − μ) / √s_t should be serially uncorrelated, and so
+ * should z²_t — what remains of an ARCH effect shows up there.
+ */
+/** z_t = (r_t − μ) / √s_t for every observation of the fit. */
+function standardizedResiduals(fit, returns) {
+    const s = fit.conditionalVariance;
+    if (returns.length !== s.length)
+        throw new RangeError(`the fit has ${s.length} variances, the returns are ${returns.length}`);
+    const z = new Float64Array(s.length);
+    for (let t = 0; t < s.length; t += 1)
+        z[t] = (returns[t] - fit.params.mu) / Math.sqrt(s[t]);
+    return z;
+}
+/** The regularised lower incomplete gamma P(a, x): its series below a + 1, its continued fraction above. */
+function lowerGamma(a, x) {
+    if (x <= 0)
+        return 0;
+    const front = Math.exp(-x + a * Math.log(x) - (0, special_js_1.logGamma)(a));
+    if (x < a + 1) {
+        let term = 1 / a;
+        let sum = term;
+        for (let n = 1; n < 1000; n += 1) {
+            term *= x / (a + n);
+            sum += term;
+            if (Math.abs(term) < Math.abs(sum) * 1e-16)
+                break;
+        }
+        return sum * front;
+    }
+    return 1 - upperFraction(a, x) * front;
+}
+/** Lentz's continued fraction for Γ(a, x) / (e^{−x} x^a / Γ(a)). */
+function upperFraction(a, x) {
+    const tiny = 1e-300;
+    let b = x + 1 - a;
+    let c = 1 / tiny;
+    let d = 1 / b;
+    let h = d;
+    for (let i = 1; i < 1000; i += 1) {
+        const an = -i * (i - a);
+        b += 2;
+        d = an * d + b;
+        if (Math.abs(d) < tiny)
+            d = tiny;
+        c = b + an / c;
+        if (Math.abs(c) < tiny)
+            c = tiny;
+        d = 1 / d;
+        const delta = d * c;
+        h *= delta;
+        if (Math.abs(delta - 1) < 1e-16)
+            break;
+    }
+    return h;
+}
+/** P(χ²_df > x), computed in the upper tail (no 1 − P cancellation for a large statistic). */
+function chiSquareSurvival(x, df) {
+    if (!(df > 0))
+        throw new RangeError(`df must be positive, got ${df}`);
+    if (!(x > 0))
+        return 1;
+    const a = df / 2;
+    const h = x / 2;
+    if (h < a + 1)
+        return 1 - lowerGamma(a, h);
+    return upperFraction(a, h) * Math.exp(-h + a * Math.log(h) - (0, special_js_1.logGamma)(a));
+}
+const checkLags = (lags, n) => {
+    if (!(Number.isInteger(lags) && lags >= 1))
+        throw new RangeError(`lags must be a positive integer, got ${lags}`);
+    if (lags >= n)
+        throw new RangeError(`${lags} lags need more than ${n} observations`);
+};
+/**
+ * Ljung–Box Q = n(n + 2)·Σ_{k ≤ lags} ρ̂²_k / (n − k) against χ²(lags − modelDf),
+ * as statsmodels' `acorr_ljungbox` (autocorrelations of the demeaned series
+ * over its total sum of squares). Run it on z for the mean, on z² for what
+ * remains of the variance dynamics.
+ */
+function ljungBox(series, lags, modelDf = 0) {
+    const n = series.length;
+    checkLags(lags, n);
+    if (!(Number.isInteger(modelDf) && modelDf >= 0 && modelDf < lags))
+        throw new RangeError(`modelDf must be an integer in [0, lags), got ${modelDf}`);
+    let mean = 0;
+    for (let t = 0; t < n; t += 1)
+        mean += series[t];
+    mean /= n;
+    let ss = 0;
+    for (let t = 0; t < n; t += 1)
+        ss += (series[t] - mean) ** 2;
+    let q = 0;
+    for (let k = 1; k <= lags; k += 1) {
+        let c = 0;
+        for (let t = k; t < n; t += 1)
+            c += (series[t] - mean) * (series[t - k] - mean);
+        q += (c / ss) ** 2 / (n - k);
+    }
+    const statistic = n * (n + 2) * q;
+    const df = lags - modelDf;
+    return { statistic, df, pValue: chiSquareSurvival(statistic, df) };
+}
+/**
+ * Engle's ARCH-LM test: e²_t regressed on a constant and e²_{t−1} … e²_{t−lags};
+ * LM = (n − lags)·R² against χ²(lags), as statsmodels' `het_arch`. On the
+ * standardised residuals, a small p-value says the model left ARCH behind.
+ */
+function archLm(series, lags) {
+    const n = series.length;
+    checkLags(lags, n);
+    const m = lags + 1;
+    const xtx = Array.from({ length: m }, () => new Array(m).fill(0));
+    const xty = new Array(m).fill(0);
+    const row = new Array(m);
+    let sumY = 0;
+    let sumY2 = 0;
+    for (let t = lags; t < n; t += 1) {
+        const y = series[t] ** 2;
+        row[0] = 1;
+        for (let k = 1; k <= lags; k += 1)
+            row[k] = series[t - k] ** 2;
+        for (let i = 0; i < m; i += 1) {
+            xty[i] += row[i] * y;
+            for (let j = 0; j <= i; j += 1)
+                xtx[i][j] += row[i] * row[j];
+        }
+        sumY += y;
+        sumY2 += y * y;
+    }
+    for (let i = 0; i < m; i += 1)
+        for (let j = i + 1; j < m; j += 1)
+            xtx[i][j] = xtx[j][i];
+    const inverse = (0, inference_js_1.invert)(xtx);
+    if (!inverse)
+        throw new RangeError('the lagged squares are collinear');
+    const beta = inverse.map((r) => r.reduce((a, v, j) => a + v * xty[j], 0));
+    const nobs = n - lags;
+    // R² = (β'X'y − n·ȳ²) / (y'y − n·ȳ²)
+    const explained = beta.reduce((a, b, i) => a + b * xty[i], 0) - (sumY * sumY) / nobs;
+    const total = sumY2 - (sumY * sumY) / nobs;
+    const statistic = nobs * (explained / total);
+    return { statistic, df: lags, pValue: chiSquareSurvival(statistic, lags) };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/cjs/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/cjs/fit.d.ts

@@ -1,8 +1,10 @@
-import { type Distribution, type GarchModel, type GarchParams } from './model.js';
+import { type Distribution, type GarchModel, type GarchParams, type MeanModel } from './model.js';
 export declare class GarchInputError extends Error {
 }
 export type FitOptions = {
     readonly model?: GarchModel;
+    /** A fitted constant (default) or zero — μ held at 0. */
+    readonly mean?: MeanModel;
     /** The innovations: normal (default, `arch`'s) or Student-t with ν fitted. */
     readonly dist?: Distribution;
     /** The lowest ν a t fit may take (default `T_NU_MIN`); must exceed 2. */
@@ -18,10 +20,17 @@ export type Inference = {
 };
 export type GarchFit = {
     readonly model: GarchModel;
+    readonly mean: MeanModel;
     readonly converged: boolean;
     readonly params: GarchParams;
     readonly persistence: number;
     readonly logLikelihood: number;
+    /** The free parameters the criteria count: μ (constant mean), ω, α, β, γ (gjr, egarch), ν (t, unless held on a bound). */
+    readonly parameterCount: number;
+    /** −2·ln L + 2k, as `arch` reports it. */
+    readonly aic: number;
+    /** −2·ln L + k·ln n, as `arch` reports it. */
+    readonly bic: number;
     /** s_t for every observation, in the returns' units squared. */
     readonly conditionalVariance: Float64Array;
     /** e_T, the last residual. */
@@ -55,8 +64,8 @@ export type GarchMode = {
 /**
  * The default floor on ν. `arch` allows 2.05, but a t variance is
  * scale²·ν/(ν − 2): near 2 it is barely defined and its forecast explodes —
- * #1111 measured AAPL and IOVA at ν̂ ≈ 2.1–2.5, most of their early origins
- * not converging and the forecast worse than naive. At 4 the kurtosis is
+ * fitted freely, AAPL and IOVA came out at ν̂ ≈ 2.1–2.5, most of their early
+ * origins not converging and the forecast worse than naive. At 4 the kurtosis is
  * still infinite but the variance forecast is stable.
  */
 export declare const T_NU_MIN = 4;