garch 1.0.0

package/build/index.mjs

@@ -0,0 +1,516 @@
+function nelderMead(fn, x0, options = {}) {
+    const { maxIter = 1000, tol = 1e-8, alpha = 1, // reflection
+    gamma = 2, // expansion
+    rho = 0.5, // contraction
+    sigma = 0.5, // shrink
+     } = options;
+    const n = x0.length;
+    // Initialize simplex
+    const simplex = [x0.slice()];
+    for (let i = 0; i < n; i++) {
+        const point = x0.slice();
+        const delta = point[i] === 0 ? 0.00025 : point[i] * 0.05;
+        point[i] += delta;
+        simplex.push(point);
+    }
+    let values = simplex.map(fn);
+    let iterations = 0;
+    let converged = false;
+    for (iterations = 0; iterations < maxIter; iterations++) {
+        // Sort simplex by function values
+        const indices = values.map((_, i) => i).sort((a, b) => values[a] - values[b]);
+        const sortedSimplex = indices.map(i => simplex[i]);
+        const sortedValues = indices.map(i => values[i]);
+        for (let i = 0; i <= n; i++) {
+            simplex[i] = sortedSimplex[i];
+            values[i] = sortedValues[i];
+        }
+        // Check convergence
+        const range = values[n] - values[0];
+        if (range < tol) {
+            converged = true;
+            break;
+        }
+        // Centroid of all points except worst
+        const centroid = new Array(n).fill(0);
+        for (let i = 0; i < n; i++) {
+            for (let j = 0; j < n; j++) {
+                centroid[j] += simplex[i][j] / n;
+            }
+        }
+        // Reflection
+        const reflected = centroid.map((c, j) => c + alpha * (c - simplex[n][j]));
+        const fr = fn(reflected);
+        if (fr < values[0]) {
+            // Expansion
+            const expanded = centroid.map((c, j) => c + gamma * (reflected[j] - c));
+            const fe = fn(expanded);
+            if (fe < fr) {
+                simplex[n] = expanded;
+                values[n] = fe;
+            }
+            else {
+                simplex[n] = reflected;
+                values[n] = fr;
+            }
+        }
+        else if (fr < values[n - 1]) {
+            simplex[n] = reflected;
+            values[n] = fr;
+        }
+        else {
+            // Contraction
+            if (fr < values[n]) {
+                // Outside contraction
+                const contracted = centroid.map((c, j) => c + rho * (reflected[j] - c));
+                const fc = fn(contracted);
+                if (fc <= fr) {
+                    simplex[n] = contracted;
+                    values[n] = fc;
+                }
+                else {
+                    // Shrink
+                    shrink(simplex, values, sigma, fn, n);
+                }
+            }
+            else {
+                // Inside contraction
+                const contracted = centroid.map((c, j) => c + rho * (simplex[n][j] - c));
+                const fc = fn(contracted);
+                if (fc < values[n]) {
+                    simplex[n] = contracted;
+                    values[n] = fc;
+                }
+                else {
+                    // Shrink
+                    shrink(simplex, values, sigma, fn, n);
+                }
+            }
+        }
+    }
+    return {
+        x: simplex[0],
+        fx: values[0],
+        iterations,
+        converged,
+    };
+}
+function shrink(simplex, values, sigma, fn, n) {
+    for (let i = 1; i <= n; i++) {
+        for (let j = 0; j < n; j++) {
+            simplex[i][j] = simplex[0][j] + sigma * (simplex[i][j] - simplex[0][j]);
+        }
+        values[i] = fn(simplex[i]);
+    }
+}
+
+/**
+ * Calculate log returns from candles
+ */
+function calculateReturns(candles) {
+    const returns = [];
+    for (let i = 1; i < candles.length; i++) {
+        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));
+    }
+    return returns;
+}
+/**
+ * Calculate log returns from price array
+ */
+function calculateReturnsFromPrices(prices) {
+    const returns = [];
+    for (let i = 1; i < prices.length; i++) {
+        if (prices[i] <= 0 || prices[i - 1] <= 0) {
+            throw new Error(`Invalid price at index ${i}`);
+        }
+        returns.push(Math.log(prices[i] / prices[i - 1]));
+    }
+    return returns;
+}
+/**
+ * Calculate sample variance (mean-zero assumption)
+ */
+function sampleVariance(returns) {
+    return returns.reduce((sum, r) => sum + r * r, 0) / returns.length;
+}
+/**
+ * Calculate sample variance with mean adjustment
+ */
+function sampleVarianceWithMean(returns) {
+    const mean = returns.reduce((sum, r) => sum + r, 0) / returns.length;
+    return returns.reduce((sum, r) => sum + (r - mean) ** 2, 0) / (returns.length - 1);
+}
+/**
+ * Check for leverage effect (asymmetry in volatility)
+ */
+function checkLeverageEffect(returns) {
+    const negative = returns.filter(r => r < 0);
+    const positive = returns.filter(r => r > 0);
+    if (negative.length === 0 || positive.length === 0) {
+        return {
+            negativeVol: 0,
+            positiveVol: 0,
+            ratio: 1,
+            recommendation: 'garch',
+        };
+    }
+    const negativeVol = Math.sqrt(negative.reduce((s, r) => s + r * r, 0) / negative.length);
+    const positiveVol = Math.sqrt(positive.reduce((s, r) => s + r * r, 0) / positive.length);
+    const ratio = negativeVol / positiveVol;
+    return {
+        negativeVol,
+        positiveVol,
+        ratio,
+        recommendation: ratio > 1.2 ? 'egarch' : 'garch',
+    };
+}
+/**
+ * Expected value of |Z| where Z ~ N(0,1)
+ * E[|Z|] = sqrt(2/π)
+ */
+const EXPECTED_ABS_NORMAL = Math.sqrt(2 / Math.PI);
+/**
+ * Calculate AIC (Akaike Information Criterion)
+ */
+function calculateAIC(logLikelihood, numParams) {
+    return 2 * numParams - 2 * logLikelihood;
+}
+/**
+ * Calculate BIC (Bayesian Information Criterion)
+ */
+function calculateBIC(logLikelihood, numParams, numObs) {
+    return numParams * Math.log(numObs) - 2 * logLikelihood;
+}
+
+/**
+ * GARCH(1,1) model
+ *
+ * σ²ₜ = ω + α·ε²ₜ₋₁ + β·σ²ₜ₋₁
+ *
+ * where:
+ * - ω (omega) > 0: constant term
+ * - α (alpha) ≥ 0: ARCH parameter (reaction to shocks)
+ * - β (beta) ≥ 0: GARCH parameter (persistence)
+ * - α + β < 1: stationarity condition
+ */
+class Garch {
+    returns;
+    periodsPerYear;
+    initialVariance;
+    constructor(data, options = {}) {
+        this.periodsPerYear = options.periodsPerYear ?? 252;
+        if (data.length < 50) {
+            throw new Error('Need at least 50 data points for GARCH estimation');
+        }
+        // Determine if input is candles or prices
+        if (typeof data[0] === 'number') {
+            this.returns = calculateReturnsFromPrices(data);
+        }
+        else {
+            this.returns = calculateReturns(data);
+        }
+        this.initialVariance = sampleVariance(this.returns);
+    }
+    /**
+     * Calibrate GARCH(1,1) parameters using Maximum Likelihood Estimation
+     */
+    fit(options = {}) {
+        const { maxIter = 1000, tol = 1e-8 } = options;
+        const returns = this.returns;
+        const n = returns.length;
+        const initVar = this.initialVariance;
+        // Negative log-likelihood function
+        function negLogLikelihood(params) {
+            const [omega, alpha, beta] = params;
+            // Constraints
+            if (omega <= 1e-12)
+                return 1e10;
+            if (alpha < 0 || beta < 0)
+                return 1e10;
+            if (alpha + beta >= 0.9999)
+                return 1e10;
+            let variance = initVar;
+            let ll = 0;
+            for (let i = 0; i < n; i++) {
+                if (i > 0) {
+                    variance = omega + alpha * returns[i - 1] ** 2 + beta * variance;
+                }
+                if (variance <= 1e-12)
+                    return 1e10;
+                // Gaussian log-likelihood (dropping constant)
+                ll += Math.log(variance) + (returns[i] ** 2) / variance;
+            }
+            return ll / 2;
+        }
+        // Initial guesses
+        const omega0 = initVar * 0.05;
+        const alpha0 = 0.1;
+        const beta0 = 0.85;
+        const result = nelderMead(negLogLikelihood, [omega0, alpha0, beta0], { maxIter, tol });
+        const [omega, alpha, beta] = result.x;
+        const persistence = alpha + beta;
+        const unconditionalVariance = omega / (1 - persistence);
+        const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
+        const logLikelihood = -result.fx * 2;
+        const numParams = 3;
+        return {
+            params: {
+                omega,
+                alpha,
+                beta,
+                persistence,
+                unconditionalVariance,
+                annualizedVol,
+            },
+            diagnostics: {
+                logLikelihood,
+                aic: calculateAIC(logLikelihood, numParams),
+                bic: calculateBIC(logLikelihood, numParams, n),
+                iterations: result.iterations,
+                converged: result.converged,
+            },
+        };
+    }
+    /**
+     * Calculate conditional variance series given parameters
+     */
+    getVarianceSeries(params) {
+        const { omega, alpha, beta } = params;
+        const variance = [];
+        for (let i = 0; i < this.returns.length; i++) {
+            if (i === 0) {
+                variance.push(this.initialVariance);
+            }
+            else {
+                const v = omega + alpha * this.returns[i - 1] ** 2 + beta * variance[i - 1];
+                variance.push(v);
+            }
+        }
+        return variance;
+    }
+    /**
+     * Forecast variance forward
+     */
+    forecast(params, steps = 1) {
+        const { omega, alpha, beta } = params;
+        const variance = [];
+        // Get last variance
+        const varianceSeries = this.getVarianceSeries(params);
+        const lastVariance = varianceSeries[varianceSeries.length - 1];
+        const lastReturn = this.returns[this.returns.length - 1];
+        // One-step ahead
+        let v = omega + alpha * lastReturn ** 2 + beta * lastVariance;
+        variance.push(v);
+        // Multi-step ahead (converges to unconditional variance)
+        for (let h = 1; h < steps; h++) {
+            v = omega + (alpha + beta) * v;
+            variance.push(v);
+        }
+        return {
+            variance,
+            volatility: variance.map(v => Math.sqrt(v)),
+            annualized: variance.map(v => Math.sqrt(v * this.periodsPerYear) * 100),
+        };
+    }
+    /**
+     * Get the return series
+     */
+    getReturns() {
+        return [...this.returns];
+    }
+    /**
+     * Get initial variance estimate
+     */
+    getInitialVariance() {
+        return this.initialVariance;
+    }
+}
+/**
+ * Convenience function to calibrate GARCH(1,1) from candles
+ */
+function calibrateGarch(data, options = {}) {
+    const model = new Garch(data, options);
+    return model.fit(options);
+}
+
+/**
+ * EGARCH(1,1) model (Nelson, 1991)
+ *
+ * ln(σ²ₜ) = ω + α·(|zₜ₋₁| - E[|z|]) + γ·zₜ₋₁ + β·ln(σ²ₜ₋₁)
+ *
+ * where:
+ * - zₜ = εₜ/σₜ (standardized residual)
+ * - ω (omega): constant term
+ * - α (alpha): magnitude effect
+ * - γ (gamma): leverage effect (typically negative)
+ * - β (beta): persistence
+ * - E[|z|] = √(2/π) for standard normal
+ */
+class Egarch {
+    returns;
+    periodsPerYear;
+    initialVariance;
+    constructor(data, options = {}) {
+        this.periodsPerYear = options.periodsPerYear ?? 252;
+        if (data.length < 50) {
+            throw new Error('Need at least 50 data points for EGARCH estimation');
+        }
+        if (typeof data[0] === 'number') {
+            this.returns = calculateReturnsFromPrices(data);
+        }
+        else {
+            this.returns = calculateReturns(data);
+        }
+        this.initialVariance = sampleVariance(this.returns);
+    }
+    /**
+     * Calibrate EGARCH(1,1) parameters using Maximum Likelihood Estimation
+     */
+    fit(options = {}) {
+        const { maxIter = 1000, tol = 1e-8 } = options;
+        const returns = this.returns;
+        const n = returns.length;
+        const initLogVar = Math.log(this.initialVariance);
+        function negLogLikelihood(params) {
+            const [omega, alpha, gamma, beta] = params;
+            // EGARCH allows negative gamma, but beta should ensure stationarity
+            if (Math.abs(beta) >= 0.9999)
+                return 1e10;
+            let logVariance = initLogVar;
+            let variance = Math.exp(logVariance);
+            let ll = 0;
+            for (let i = 0; i < n; i++) {
+                if (i > 0) {
+                    const sigma = Math.sqrt(variance);
+                    const z = returns[i - 1] / sigma;
+                    logVariance = omega
+                        + alpha * (Math.abs(z) - EXPECTED_ABS_NORMAL)
+                        + gamma * z
+                        + beta * logVariance;
+                    // Prevent extreme values
+                    logVariance = Math.max(-50, Math.min(50, logVariance));
+                    variance = Math.exp(logVariance);
+                }
+                if (variance <= 1e-12 || !isFinite(variance))
+                    return 1e10;
+                ll += Math.log(variance) + (returns[i] ** 2) / variance;
+            }
+            return ll / 2;
+        }
+        // Initial guesses
+        // omega approximates log of unconditional variance when other params are small
+        const omega0 = initLogVar * 0.1;
+        const alpha0 = 0.1;
+        const gamma0 = -0.05; // Negative for typical leverage effect
+        const beta0 = 0.95;
+        const result = nelderMead(negLogLikelihood, [omega0, alpha0, gamma0, beta0], { maxIter, tol });
+        const [omega, alpha, gamma, beta] = result.x;
+        // For EGARCH, unconditional variance: E[ln(σ²)] = ω/(1-β)
+        // So E[σ²] ≈ exp(ω/(1-β)) when α and γ effects average out
+        const unconditionalLogVar = omega / (1 - beta);
+        const unconditionalVariance = Math.exp(unconditionalLogVar);
+        const annualizedVol = Math.sqrt(unconditionalVariance * this.periodsPerYear) * 100;
+        const logLikelihood = -result.fx * 2;
+        const numParams = 4;
+        return {
+            params: {
+                omega,
+                alpha,
+                gamma,
+                beta,
+                persistence: beta, // In EGARCH, persistence is primarily driven by beta
+                unconditionalVariance,
+                annualizedVol,
+                leverageEffect: gamma,
+            },
+            diagnostics: {
+                logLikelihood,
+                aic: calculateAIC(logLikelihood, numParams),
+                bic: calculateBIC(logLikelihood, numParams, n),
+                iterations: result.iterations,
+                converged: result.converged,
+            },
+        };
+    }
+    /**
+     * Calculate conditional variance series given parameters
+     */
+    getVarianceSeries(params) {
+        const { omega, alpha, gamma, beta } = params;
+        const variance = [];
+        let logVariance = Math.log(this.initialVariance);
+        for (let i = 0; i < this.returns.length; i++) {
+            if (i === 0) {
+                variance.push(this.initialVariance);
+            }
+            else {
+                const sigma = Math.sqrt(variance[i - 1]);
+                const z = this.returns[i - 1] / sigma;
+                logVariance = omega
+                    + alpha * (Math.abs(z) - EXPECTED_ABS_NORMAL)
+                    + gamma * z
+                    + beta * logVariance;
+                logVariance = Math.max(-50, Math.min(50, logVariance));
+                variance.push(Math.exp(logVariance));
+            }
+        }
+        return variance;
+    }
+    /**
+     * Forecast variance forward
+     *
+     * Note: EGARCH forecasts are more complex because they depend on
+     * the path of shocks. This provides an approximation assuming
+     * expected values of future shocks.
+     */
+    forecast(params, steps = 1) {
+        const { omega, alpha, gamma, beta } = params;
+        const variance = [];
+        const varianceSeries = this.getVarianceSeries(params);
+        const lastVariance = varianceSeries[varianceSeries.length - 1];
+        const lastReturn = this.returns[this.returns.length - 1];
+        // One-step ahead using actual last return
+        const sigma = Math.sqrt(lastVariance);
+        const z = lastReturn / sigma;
+        let logVariance = omega
+            + alpha * (Math.abs(z) - EXPECTED_ABS_NORMAL)
+            + gamma * z
+            + beta * Math.log(lastVariance);
+        variance.push(Math.exp(logVariance));
+        // Multi-step: assume E[z] = 0, E[|z|] = √(2/π)
+        // So the α and γ terms contribute 0 on average
+        for (let h = 1; h < steps; h++) {
+            logVariance = omega + beta * logVariance;
+            variance.push(Math.exp(logVariance));
+        }
+        return {
+            variance,
+            volatility: variance.map(v => Math.sqrt(v)),
+            annualized: variance.map(v => Math.sqrt(v * this.periodsPerYear) * 100),
+        };
+    }
+    /**
+     * Get the return series
+     */
+    getReturns() {
+        return [...this.returns];
+    }
+    /**
+     * Get initial variance estimate
+     */
+    getInitialVariance() {
+        return this.initialVariance;
+    }
+}
+/**
+ * Convenience function to calibrate EGARCH(1,1) from candles
+ */
+function calibrateEgarch(data, options = {}) {
+    const model = new Egarch(data, options);
+    return model.fit(options);
+}
+
+export { EXPECTED_ABS_NORMAL, Egarch, Garch, calculateReturns, calculateReturnsFromPrices, calibrateEgarch, calibrateGarch, checkLeverageEffect, nelderMead, sampleVariance, sampleVarianceWithMean };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "garch",
+  "version": "1.0.0",
+  "description": "GARCH and EGARCH volatility models for TypeScript",
+  "type": "module",
+  "main": "./build/index.cjs",
+  "module": "./build/index.mjs",
+  "types": "./types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./build/index.mjs",
+      "require": "./build/index.cjs"
+    }
+  },
+  "files": [
+    "build",
+    "types.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "garch",
+    "egarch",
+    "volatility",
+    "finance",
+    "econometrics",
+    "time-series"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^20.10.0",
+    "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"
+  }
+}